diff --git a/README.md b/README.md index 7c0c035..902f93f 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Hallmark picks a macrostructure for the brief, dresses it in one of twenty-two t | *(default)* | Build new UI. Picks a macrostructure, applies the rule-set, runs the slop test before handing back. | | `hallmark audit ` | Score existing code against the anti-patterns. Punch list, no edits. | | `hallmark redesign ` | Throw out the structure, keep copy + IA + brand, rebuild with a different fingerprint. | -| `hallmark study ` | Extract the **DNA** from a design you admire — macrostructure, type-pairing, colour anchor. Refuses pixel-clones, paid templates, and competitor pages. Optionally emits a portable `design.md` for handoff to other AI tools. | +| `hallmark study ` | Extract the **DNA** from a design you admire — macrostructure, type-pairing, colour anchor. Refuses pixel-clones and paid templates. Optionally emits a portable `design.md` for handoff to other AI tools. | --- diff --git a/SKILL.md b/SKILL.md index 57e7adf..3013339 100644 --- a/SKILL.md +++ b/SKILL.md @@ -25,7 +25,7 @@ Hallmark has one default behaviour and three explicit verbs. | *(default)* | The user asked you to design or build something new. Follow the **Design flow** below. | | `hallmark audit ` | Read the target, score it against the anti-pattern list, return a ranked punch list. **Do not edit.** | | `hallmark redesign [--mood ]` | Take the target's content and intent, then redesign the visual structure **inside the existing implementation boundaries unless the user explicitly confirms a full rebuild.** New section rhythm, new heading placement, new component voice. Preserve existing routes, component ownership, copy intent, brand, and information architecture; replace only the visual/interaction layer needed for the requested scope. | -| `hallmark study ` | The user pasted or attached an image of a design they admire, **or** pasted a URL to a live page. Extract the **DNA** — macrostructure, archetypes, type-pairing, colour anchor — and produce a diagnosis report, then optionally rebuild the user's content using the extracted DNA **or** emit a portable `design.md` of the DNA. Detection is automatic: a URL (`http://` / `https://` prefix) routes to URL mode; anything else routes to image mode. **URL mode** reads the page's HTML and CSS via WebFetch — it can name exact fonts and exact colour values, but can't judge rhythm. After the diagnosis, the user has three follow-ups: build with the DNA (handoff to default), lock the DNA into a portable `design.md` (opt-in via "lock the DNA" / "give me a design.md"), or stop at the diagnosis. **Never copies pixels. Refuses template-marketplace URLs and competitor pages. Tighter refusal layer for `design.md` emission than for the diagnosis itself — URL-mode emission requires attestation that the source is the user's own or a public reference for their own brand. Falls back to asking for a screenshot if the URL is auth-walled, a JS-only SPA shell, or otherwise un-readable.** Load [`references/study.md`](references/study.md) before this verb runs. | +| `hallmark study ` | The user pasted or attached an image of a design they admire, **or** pasted a URL to a live page. Extract the **DNA** — macrostructure, archetypes, type-pairing, colour anchor — and produce a diagnosis report, then optionally rebuild the user's content using the extracted DNA **or** emit a portable `design.md` of the DNA. Detection is automatic: a URL (`http://` / `https://` prefix) routes to URL mode; anything else routes to image mode. **URL mode** reads the page's HTML and CSS via WebFetch — it can name exact fonts and exact colour values, but can't judge rhythm. After the diagnosis, the user has three follow-ups: build with the DNA (handoff to default), lock the DNA into a portable `design.md` (opt-in via "lock the DNA" / "give me a design.md"), or stop at the diagnosis. **Never copies pixels. Refuses template-marketplace URLs. Tighter refusal layer for `design.md` emission than for the diagnosis itself — URL-mode emission requires attestation that the source is the user's own or a public reference for their own brand. Falls back to asking for a screenshot if the URL is auth-walled, a JS-only SPA shell, or otherwise un-readable.** Load [`references/study.md`](references/study.md) before this verb runs. | If the user types anything that does not clearly map to `audit`, `redesign`, or `study`, treat it as default. If the user attaches an image or pastes a URL without a verb prefix, ask: *"Should I `study` this (extract the DNA), or should I treat it as a reference for a fresh build?"* @@ -494,7 +494,7 @@ If the user's input starts with `http://` or `https://` → **URL mode**. Otherw ### Pipeline -1. **Refuse-or-proceed check.** Before extracting anything (and in URL mode, **before WebFetch fires**), run the refusal heuristics in `study.md`. Image mode checks the image's content; URL mode runs the URL refuse list (themeforest, framer.com/templates, webflow.com/templates, gumroad UI-kit listings, dribbble shots, behance galleries, disclosed competitors). Ambiguous sources get one short question: *"Is this your own work, a public reference for inspiration, or someone else's live site?"* +1. **Refuse-or-proceed check.** Before extracting anything (and in URL mode, **before WebFetch fires**), run the refusal heuristics in `study.md`. Image mode checks the image's content; URL mode runs the URL refuse list (themeforest, framer.com/templates, webflow.com/templates, gumroad UI-kit listings, dribbble shots, behance galleries). Ambiguous sources get one short question: *"Is this your own work, a public reference for inspiration, or someone else's live site?"* 2. **Extraction pass.** - **Image mode:** vision-pass on the attached capture per `study.md` § Five-step protocol. diff --git a/docs/study-examples.md b/docs/study-examples.md index 8aa3678..4914774 100644 --- a/docs/study-examples.md +++ b/docs/study-examples.md @@ -12,7 +12,7 @@ The whole point of `study`: extract **structural DNA** (macrostructure + archety ### Refuse-or-proceed check -Public reference for inspiration → proceed. (Refusal heuristics fire on: paid-template-marketplace listings, competitor live marketing pages, copy-protected portfolios. None match.) +Public reference for inspiration → proceed. (Refusal heuristics fire on: paid-template-marketplace listings, copy-protected portfolios. None match.) ### Diagnosis report (what `study` returns first) @@ -114,7 +114,7 @@ The homepage emits the agency's mark in 22-rem Bricolage 800, ruled grid behind, ### Refuse-or-proceed check -A *competitor's live portfolio* is the edge case here. Per `study.md` § Refusal heuristics: if the user is in the same domain as the screenshot subject, ask first. +An ambiguous source is the edge case here. Per `study.md` § Refusal heuristics: when you can't tell whether the source is the user's own work or someone else's, ask first. > *"Is this your own work, a public reference for inspiration, or someone else's live site? If it's someone else's live site, I'll extract the DNA at the structural level only — no copy, no demos, no font IDs — and you'll bring your own content. If it's a paid portfolio template, I won't reproduce it."* @@ -170,7 +170,7 @@ Output: the user's actual name in italic-Fraunces top-left, their demo (e.g. an 1. **Names the font role, not the font ID.** Visual font identification is unreliable. The skill proposes one or two real candidates from the canon and asks the user to confirm. 2. **Never copies pixels.** The DNA is the macrostructure + archetype + colour-anchor + type-pairing — not the dress. -3. **Refuses the obvious bad sources.** Paid-template-marketplace listings; competitor live marketing pages without explicit user confirmation; copy-protected portfolios without permission. +3. **Refuses the obvious bad sources.** Paid-template-marketplace listings; copy-protected portfolios without permission. 4. **Always disclosures the substitutions.** When the screenshot's font is paid (Tiempos / Söhne / Druk) and the user hasn't confirmed a licence, the skill names a free understudy (Fraunces / Inter Tight / Bricolage Grotesque) and *says it's substituting*. These three examples cover the most common categories of `study` request: an editorial portfolio, a type-specimen statement page, and a small personal site. The protocol is the same for every screenshot — refuse-or-proceed, diagnose, confirm, build. See [`study.md`](study.md) for the full protocol. diff --git a/references/study.md b/references/study.md index 77df61a..175a296 100644 --- a/references/study.md +++ b/references/study.md @@ -61,14 +61,13 @@ Run this check **before** extracting anything. If any of the following is true, | If the screenshot is… | Then… | | --- | --- | | A paid template marketplace listing (ThemeForest, Gumroad templates, Webflow templates, Framer templates, Notion templates) | Refuse. Suggest: "Tell me what you like about it and I'll build with `hallmark default` instead." | -| A live competitor's marketing page where the user's intent is replication | Refuse. Suggest: "I can extract the structural pattern but won't reproduce a competitor's surface. Would the pattern alone be useful?" | | A famous designer's signature work (Pentagram project pages, Klim foundry specimens, Mathieu Triay's portfolio, etc.) being treated as a template | Soft-refuse. Acknowledge the source by name, extract DNA only, and refuse to copy distinctive choices that read as that designer's signature. | | Copyrighted artwork, photography, or illustrations as the design's centerpiece | Refuse to reproduce the artwork. The DNA can still be extracted (the *fact* that the page uses one big image as its hero is structural; the specific image is not). | | A user's own previous work | Proceed. | | A public reference site the user is using for inspiration on their own brand | Proceed. State the source if known. | -| Anything ambiguous | **Ask once:** *"Is this your own work, a public reference, or someone else's live site? If it's a competitor or a marketplace template, I'll skip the build and just give you the diagnosis."* | +| Anything ambiguous | **Ask once:** *"Is this your own work, a public reference, or someone else's live site? If it's a marketplace template, I'll skip the build and just give you the diagnosis."* | -**Never** silently proceed when you suspect the screenshot is a marketplace listing or a competitor. The user must explicitly confirm. The cost of asking is low; the cost of building a knockoff is reputational. +**Never** silently proceed when you suspect the screenshot is a marketplace listing. The user must explicitly confirm. The cost of asking is low; the cost of building a knockoff is reputational. ### URL refuse list (auto-refuse on domain match) @@ -80,8 +79,7 @@ In URL mode, run this **before** WebFetch fires — don't even fetch the page. I | `framer.com/templates/*`, `*.framer.website` (Framer marketplace + template demos), `webflow.com/templates/*` (Webflow templates) | Refuse same as above — these are the marketplace ecosystem by another name. | | `gumroad.com/*` where the page is selling a UI kit or template (heuristic: `og:type=product` plus *template*, *UI kit*, *starter*, *bundle* in the title) | Refuse. | | `dribbble.com/shots/*`, `behance.net/gallery/*` (designer presentation work) | Soft-refuse. *"These are individual designers' presentation pieces — I'll extract DNA only, not reproduce signature choices. If a specific designer's voice resonates, tell me what about it does."* | -| Any URL the user discloses as a direct competitor | Refuse the build. *"I'll extract the structural pattern but won't reproduce a competitor's surface. Would the pattern alone be useful?"* | -| Anything ambiguous (an unfamiliar agency page, a personal portfolio, an unknown SaaS) | **Ask once:** *"Is this your own site, a public reference you admire, or a competitor? If competitor or marketplace, I'll skip the build and give you the diagnosis only."* | +| Anything ambiguous (an unfamiliar agency page, a personal portfolio, an unknown SaaS) | **Ask once:** *"Is this your own site, a public reference you admire, or someone else's live site? If it's a marketplace template, I'll skip the build and give you the diagnosis only."* | The image-mode refusal rules above still apply by analogy in URL mode — if the page reads as signature work from a known designer, soft-refuse the same way. @@ -181,7 +179,7 @@ After the five-step pass, fill out this schema. The diagnosis report is built fr "source_mode": "image | url", "source_url": "", "source": "user-described | public-reference | unknown", - "refusal": "ok | refused (paid-template) | refused (competitor) | soft-refusal (signature work)", + "refusal": "ok | refused (paid-template) | soft-refusal (signature work)", "macrostructure": "", "macrostructure_alt":"", "hero": { @@ -423,7 +421,7 @@ If the user just confirms the diagnosis without naming emission, **do not emit** ### The emission-refusal layer (tighter than diagnosis refusal) -Diagnosis refusal asks: *"can I read this without crossing the line into cloning a competitor or copying a paid template?"* The answer is usually yes — reading is cheap and educational. +Diagnosis refusal asks: *"can I read this without copying a paid template?"* The answer is usually yes — reading is cheap and educational. Emission refusal asks: *"can I package this DNA as a portable system the user (or any AI tool the user hands the file to) will then use as their own design language?"* That's meaningfully more extractive than a diagnosis. The user already has the diagnosis; the file is a separate, durable artifact that travels. @@ -437,7 +435,7 @@ The two refusal layers do not match. A reference can clear the diagnosis bar and > > *(a) your own site* > *(b) a public reference for your own brand (you have permission to learn from it)* -> *(c) something else (a competitor, a designer you admire, a stranger's site you stumbled on)* +> *(c) something else (a designer you admire, a stranger's site you stumbled on)* > > *Reply (a), (b), or (c).* @@ -449,9 +447,9 @@ Then dispatch on the answer: | (b) "public reference for own brand" | Emit, but include a `## Provenance` block: *"Extracted from `` as a public reference for the user's brand on . The DNA is structural; specific tokens may need to be regenerated to match the user's brand identity rather than the source's."* | | (c) "something else" | **Refuse.** *"I won't emit a `design.md` from a third-party site I'm not authorised to extract from. The diagnosis is yours — that's a learning tool. The portable spec needs a source you can attest authorship of, or a public reference for your own brand. If you want a design.md anyway, take a screenshot of your own moodboard or your own existing site, and I'll study that instead."* | -If the user has already disclosed source attribution earlier in the conversation (e.g., during the initial "is this your own work / public reference / competitor" check, they answered "my own site"), do not re-ask — carry that attestation forward. The ask is only needed when status is unknown. +If the user has already disclosed source attribution earlier in the conversation (e.g., during the initial "is this your own work / public reference / someone else's site" check, they answered "my own site"), do not re-ask — carry that attestation forward. The ask is only needed when status is unknown. -The image-mode refusal table at the top of this file still applies in both modes. A source that already failed the diagnosis refusal (paid template, declared competitor, soft-refused signature work) is auto-refused at emission — do not re-ask. +The image-mode refusal table at the top of this file still applies in both modes. A source that already failed the diagnosis refusal (paid template, soft-refused signature work) is auto-refused at emission — do not re-ask. ### What gets written diff --git a/site/_tests/verbs/study/input-description.md b/site/_tests/verbs/study/input-description.md index f44c197..3762f26 100644 --- a/site/_tests/verbs/study/input-description.md +++ b/site/_tests/verbs/study/input-description.md @@ -26,4 +26,4 @@ The user pasted a screenshot of a design studio's portfolio site they admire. Be ## Refusal heuristics check -The screenshot is a public reference (a real studio's published portfolio, not a paid template). The user is in a related domain (small studio) but not a direct competitor. **Proceed with DNA extraction at the structural level only — no copy, no pixel-faithful reproduction.** +The screenshot is a public reference (a real studio's published portfolio, not a paid template). **Proceed with DNA extraction at the structural level only — no copy, no pixel-faithful reproduction.** diff --git a/site/_tests/verbs/study/notes.md b/site/_tests/verbs/study/notes.md index a84a0dd..af13c4f 100644 --- a/site/_tests/verbs/study/notes.md +++ b/site/_tests/verbs/study/notes.md @@ -6,11 +6,11 @@ A described screenshot (`input-description.md`) of a Pentagram-style design stud ## What `study` does -> *"Extract the DNA — macrostructure, archetypes, type-pairing role, colour anchor, rhythm — and produce a diagnosis report, then optionally rebuild the user's content using the extracted DNA. Never copies pixels. Never claims to identify exact fonts. Refuses obvious template-marketplace or competitor-page screenshots."* +> *"Extract the DNA — macrostructure, archetypes, type-pairing role, colour anchor, rhythm — and produce a diagnosis report, then optionally rebuild the user's content using the extracted DNA. Never copies pixels. Never claims to identify exact fonts. Refuses obvious template-marketplace screenshots."* Five-step pipeline (per [`SKILL.md`](../../../SKILL.md) § `hallmark study`): -1. **Refuse-or-proceed check** — public reference, not a paid template, not a direct competitor's live page → proceed. +1. **Refuse-or-proceed check** — public reference, not a paid template → proceed. 2. **Vision pass** — read the image into the structured-fields schema in [`study.md`](../../../references/study.md). Output ten fields. 3. **Diagnosis report** — return the named macrostructure + archetypes + anti-patterns to NOT carry over. See [`diagnosis.md`](diagnosis.md). 4. **Confirmation question** — ask before building. @@ -51,11 +51,11 @@ The `studied: yes` flag tells future `audit` runs to be lenient on "Specimen-fal The screenshot maps neatly to study-examples.md Example A (Pentagram-style editorial portfolio). It exercises: -- The refusal heuristics (public reference, not a competitor → proceed). +- The refusal heuristics (public reference, not a paid template → proceed). - The 10-field structured schema. - The font-role-not-font-ID discipline. - The "anti-patterns the screenshot has — do NOT carry over" output. - The confirmation question. - The `studied: yes` stamp. -If the input had been a paid Squarespace-template marketplace screenshot, the verb would have refused. If the input had been a direct competitor's live site, the verb would have asked before extracting. Both branches are documented in [`study.md`](../../../references/study.md); this test exercises the proceed-with-public-reference branch. +If the input had been a paid Squarespace-template marketplace screenshot, the verb would have refused. If the input had been ambiguous (an unknown agency page or a personal portfolio with no clear ownership), the verb would have asked before extracting. Both branches are documented in [`study.md`](../../../references/study.md); this test exercises the proceed-with-public-reference branch.