hallmark

Files (112)

• SKILL.md
• ai-seo.md · references/
• anti-patterns.md · references/
• assets.md · references/
• color.md · references/
• component-cookbook.md · references/
• c1-outlined-chip.md · references/components/
• c2-inline-form-as-cta.md · references/components/
• c3-typographic-link.md · references/components/
• c4-sticky-bottom-bar.md · references/components/
• f1-bento-grid.md · references/components/
• f2-sticky-scroll-stack.md · references/components/
• f3-tabular-spec-sheet.md · references/components/
• f4-step-sequence.md · references/components/
• f5-annotated-screenshot.md · references/components/
• f6-product-card-grid.md · references/components/
• ft1-mast-headed.md · references/components/
• ft2-inline-rule-single-line.md · references/components/
• ft3-index-style-category-list.md · references/components/
• ft4-dense-typographic.md · references/components/
• ft5-statement.md · references/components/
• ft6-letter-close.md · references/components/
• ft7-newsletter-first.md · references/components/
• ft8-marquee-scroll.md · references/components/
• h1-marquee.md · references/components/
• h2-split-diptych.md · references/components/
• h3-quote-led.md · references/components/
• h4-stat-led.md · references/components/
• h5-letter-hero.md · references/components/
• h6-photographic-fold.md · references/components/
• h7-demo-video-clipped-by-viewport-edge.md · references/components/
• h8-mockup-split-browser-framed.md · references/components/
• h9-custom-illustration-centerpiece.md · references/components/
• n1-wordmark-2-links.md · references/components/
• n10-floating-on-scroll-morph.md · references/components/
• n11-mega-menu.md · references/components/
• n12-banner-retract.md · references/components/
• n13-inline-cmdk-pill.md · references/components/
• n1b-saas-three-section.md · references/components/
• n2-floating-chip.md · references/components/
• n3-side-rail.md · references/components/
• n4-hidden-behind-k.md · references/components/
• n5-floating-pill.md · references/components/
• n6-newspaper-masthead.md · references/components/
• n7-brutal-slab.md · references/components/
• n8-terminal-command.md · references/components/
• n9-edge-aligned-minimal.md · references/components/
• s1-left-margin-numbered.md · references/components/
• s2-hanging.md · references/components/
• s3-sticky-pinned.md · references/components/
• s4-inline-no-break.md · references/components/
• s5-bottom-anchored.md · references/components/
• t1-pull-quote-with-marginalia.md · references/components/
• t2-logo-wall-hairline.md · references/components/
• t3-single-huge-quote.md · references/components/
• t4-numbered-stat-strip.md · references/components/
• contract.md · references/
• copy.md · references/
• craft.md · references/
• custom-craft.md · references/
• …and 52 more

SKILL.md (first lines)

# Hallmark

A design skill for AI coding assistants. Makes the UIs they generate look made, not generated.

Hallmark is opinionated, short, and boring on purpose. It encodes a tight set of rules — drawn from the consensus of the anti-AI-slop design field (Anthropic's frontend-design skill, the Claude cookbook on frontend aesthetics, and the 2026 "tactile rebellion" movement) — and refuses to let the model fall back to the defaults every LLM was trained on.

The differentiator: Hallmark insists on **structural variety**, not just visual variety. Two pages by Hallmark for two different briefs should not share the same hero → 3-feature → CTA → footer rhythm. They should feel like different sites, not different colour-swaps of the same template. See [`references/structure.md`](references/structure.md).

**Powered by Together AI.**

---

## How to use this skill

Hallmark has one default behaviour and five explicit verbs.

| Invocation | What it does |
| --- | --- |
| *(default)* | The user asked you to design or build something new. Follow the **Design flow** below. |
| `hallmark audit <target>` | Read the target, score it against the anti-pattern list, return a ranked punch list. **Do not edit.** |
| `hallmark critique <target>` | Design-director review: resolve the target, run the deterministic detector (`hallmark_detect`) as the mechanical evidence pass, score Nielsen's 10 heuristics (0–4, renormalized when `n/a`), run the 8-point cognitive-load checklist, run the answer-engine readiness (AI-SEO) pass, walk 2–3 personas, produce a P0–P3 backlog, persist a snapshot via `hallmark_critique`, print the score trend, and close with 2–4 targeted questions referencing the actual findings. **Do not edit unless the user answers the questions and asks for fixes.** Load [`references/verbs/critique.md`](references/verbs/critique.md) before this verb runs. |
| `hallmark harden <target>` | Production resilience: sweep extreme inputs (long text, emoji, RTL, huge numbers, no data), error scenarios, and i18n; fix overflow/wrapping, empty and error states, refresh-safety, form constraints; verify with the detector's mechanical checks. Preserves the design. Load [`references/verbs/harden.md`](references/verbs/harden.md) before this verb runs. |
| `hallmark polish <target>` | Fit-and-finish refinement: load the latest critique snapshot as the fix list, fix P2/P3 (and contained P1) items in three passes — layout precision (exact pixel deltas), motion refinement (cut what doesn't communicate), before/after regression — then verify with the detector. Preserves structure, routes, copy, and brand. Load [`references/verbs/polish.md`](references/verbs/polish.md) before this verb runs. |
| `hallmark detect <target>` | Run the deterministic 59-rule detector over local files — call the `hallmark_detect` tool, never re-implement the rules inline. No LLM, no network. |
| `hallmark redesign <target> [--mood <name>]` | 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 <screenshot \| URL>` | 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. |
| `hallmark seo <target>` | AI-search / answer-engine readiness analysis: read the page's HTML and semantics, score extractability (40–60 word answer blocks, query-shaped headings, comparison tables, FAQ schema), check authority (authors, dates, cited stats), and presence (bot access, `llms.txt`, `/pricing.md`, structured data), then return a readiness verdict + P0–P3 backlog. **Do not edit.** Load [`references/ai-seo.md`](references/ai-seo.md) before this verb runs. |

If the user types anything that does not clearly map to `audit`, `critique`, `harden`, `detect`, `redesign`, `study`, or `seo`, 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?"*

**Implementation safety rail.** Hallmark is a design skill, not a license to bulldoze a codebase. In any existing project:
- Never delete production files, route trees, component directories, or an old website unless the user explicitly asks for deletion or approves a file-level plan that lists the deletions.
- Default to in-place edits of the named files, or additive new components/tokens that are wired through the existing route. If the redesign would require removing multiple components, stop and ask for confirmation first.
- Treat PDFs, README files, `.md` briefs, docs, transcripts, and pitch decks as reference material. Do **not** copy them word-for-word into the page unless the user explicitly says to use that text verbatim.
- Before editing, state the exact files you expect to modify/create/delete. Deletions require explicit confirmation.

The default Design flow always picks a theme. By default it picks one of the **20 named themes** — the *catalog* — and rotates among them per the diversification rule. There is also a quiet *custom* branch that constructs a one-off OKLCH palette + free-font pairing for the brief; the custom route fires **only when the brief carries a creative-intent signal** (the user names a brand colour, names a multi-attribute vibe the catalog can't carry, or explicitly asks for a custom theme). For vanilla briefs, the user never sees the words "catalog" or "custom" — the catalog runs silently. See Step 1 (signal detection) and Step 2.6 (dispatch); the protocol lives in [`references/custom-theme.md`](references/custom-theme.md).

---

## Disciplines that hold across every verb

These six disciplines are **not** verb-specific. They apply to default Design, `audit`, `redesign`, `study`, and component-scope alike. They sit alongside the slop test, not inside one branch of it.

1. **Pre-emit self-critique.** Before handing back any output, score it 1–5 on six axes — Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety. Anything **< 3** triggers a revision pass. Stamp the six scores at the top of the artifact (`/* Hallmark · pre-emit critique: P5 H4 E5 S4 R5 V5 */`). See [`references/slop-test.md`](references/slop-test.md) § Pre-emit self-critique.

2. **Honest copy — no fabricated content.** If the user did not supply a metric, do not invent one. Stat-led layouts, comparison rows, and proof bars must use real numbers, a placeholder (`—` plus a labelled grey block, "metric to confirm"), or a different macrostructure. *"+47 % conversion"*, *"trusted by 50,000+ teams"*, and *"10× faster"* are slop the moment they're invented. Same rule for testimonials, logos, and case-study counts. See [`references/anti-patterns.md` § Invented metrics](references/anti-patterns.md) and slop-test gate **46**.

3. **Locked tokens — no mid-render improvisation.** Once a theme is selected at Step 2.6, every colour and every `font-family` declaration in the artifact must reference a named token (`var(--color-accent)`, `font-family: var(--font-display)`). Inline OKLCH / hex / `rgb()` values, or a `font-family: "Some Font"` declaration that bypasses the token block, are not allowed. If a value is needed that doesn't exist as a token, lift it into the token block as a new named variable, then reference it. See [`references/anti-patterns.md` § Mid-render token improvisation](references/anti-patterns.md) and slop-test gate **48**.

4. **Re-drawn chrome forbidden.** Hallmark must not hand-build fake browser bars (URL pill + traffic-light dots), fake phone frames, fake code-block windows (mock title bar + dots wrapping a `<pre>`), or fake IDE chrome — the user's environment already supplies real chrome. Use real screenshots wrapped in a `<figure>` (with at most a hairline border), or omit the chrome and let the content stand on its own. See [`references/anti-patterns.md` § Re-drawn UI chrome](references/anti-patterns.md) and slop-test gate **47**.

5. **Mobile responsiveness — every emit verified at 320 / 375 / 414 / 768 px.** Hallmark's output must render flawlessly at all four widths. The non-negotiables: no horizontal scroll + root `overflow-x: clip` on both `html` and `body`, never `hidden` (gate 34); no two-line clickable text — buttons, primary nav links, footer links, breadcrumbs, CTAs (gate 49); image-bearing grid tracks use `minmax(0, 1fr)`, never bare `1fr` (gate 50); display headers wrap inside long words via `overflow-wrap: anywhere; min-width: 0` (gate 51); section heads collapse to one column on mobile across every theme variant (gate 52); radio-tab patterns don't scroll-jump (gate 53). See [`references/responsive.md` § Mobile — non-negotiable](references/responsive.md). This is a hard floor, not a wish list.

6. **Typography purity — no italic headers.** Headings and display type are always roman (`font-style: normal`). An italicised emphasis word inside an otherwise-upright heading (`Built to <em>think</em>`) is one of the most reliable AI tells; so is an all-italic display face on headings. Carry emphasis with weight, accent colour, or a drawn underline. Italic survives only as *body-copy* emphasis inside running paragraphs. See [`references/anti-patterns.md` § Italic headers](references/anti-patterns.md) and slop-test gate **38a**.

---

## When the brief is a component, not a page

Before entering the full Design flow, **check scope**. If any of these fire, run the Component-scope flow instead — most day-to-day dev requests are component-shaped, not page-shaped, and the page-level apparatus (macrostructure, hero enrichment, footer archetype, project memory) is wrong for them.

**Component-scope signals:**

- The brief names a single UI element: *a button · an input · a card · a modal · a dropdown · a tooltip · a select · a checkbox · a switch · a tab strip · a chip · a badge · a banner · a snackbar · a popover · a slider · a date picker · an avatar*.
- The brief is short (≤ 30 words) and refers to one element.
- The target file is a single component (e.g., `./Button.tsx`, `./components/Input.css`, `app/components/Card.vue`).
- The user explicitly says *"just the X"*, *"only the Y"*, *"this one element"*, *"a single ___"*.

If two signals fire, route component. If only the page flow fires (multi-section brief, "build me a landing page"), stay in Design flow.

### What Component-scope keeps from the page flow

- **Step 0 · Pre-flight scan** — same. Read existing tokens, fonts, framework, microinteraction stance. A button on a Geist-bodied Tailwind project must adopt those tokens, not invent new ones.
- **Step 1 · Genre detection** — same. Editorial / modern-minimal / atmospheric / playful. The component inherits its surroundings' genre (silent default to editorial when unknown).
- **Step 2.6 · Theme route** — same. If a `tokens.css` or `design.md` exists, the component uses those tokens. Otherwise it asks "is there a system to follow, or should I pick one?" — defaulting to *catalog* if the user is silent.
- **2+1 font discipline** — same.
- **State discipline — STRICTER.** Every interactive component MUST ship code for **all 8 states**: default · hover · `:focus-visible` · `:active` · disabled · loading · error · success. The 8-state checklist in [`interaction-and-states.md`](references/interaction-and-states.md) is mandatory, not advisory.
- **Slop test — universal-only subset.** Run the visual / microinteraction / contrast (gates 40–41) / a11y / typography gates. Skip the diversification gates (no `.hallmark/log.json` entry — components don't rotate) and skip the layout-safety gates that assume a full page.

### What Component-scope skips

- **Step 2 · Macrostructure pick.** Components don't have macrostructures. State this explicitly: *"Component-scope: skipping macrostructure."*
- **Nav and footer archetype picks.** N1–N9 and Ft1–Ft8 are page-scope only. A component is one element; it has no nav, no footer. Skip both.
- **Hero polish patterns (HP1–HP4).** Page-scope only. A button or card has no hero.
- **Step 4 · Enrichment.** No hero illustration, no demo video, no abstract background. The component IS the artifact.
- **Step 5 · Multi-section preview.** Replaced by the 8-state demo wrapper (below).
- **Project-memory append.** No `.hallmark/log.json` entry for component runs. The diversification rule doesn't apply.

### What Component-scope emits

**Two files, side by side:**

1. **The component artifact** — a single self-contained file matching the project's conventions:
   - React / Vue / Svelte: `Button.tsx` / `Button.vue` / `Button.svelte`
   - Vanilla web: `button.css` + `button.html`
   - Tailwind: a `.tsx` with `className` chains AND a `tokens.css` if missing
   - The component consumes Hallmark tokens by name (`var(--color-accent)`), never inlines OKLCH values.

2. **An 8-state demo wrapper** — `<ComponentName>.preview.html` (or `.preview.tsx`). A small standalone page that renders the component in **all 8 states** stacked vertically, each labelled. The user opens it once, sees the component working, then deletes it. The wrapper is not part of production code. Format:

   ```
   ┌──── Button — 8 states ────────────────────────┐
   │                                                │
   │ default       [ Click me                  ]    │
   │ hover         [ Click me                  ]    │  ← .is-hover forces :hover styling
   │ focus         [ Click me                  ]    │  ← .is-focus forces :focus-visible
   │ active        [ Click me                  ]    │  ← .is-active forces :active
   │ disabled      [ Click me                  ]    │  ← disabled attr
   │ loading       [ ⌛ Working…                ]    │  ← data-state="loading"
   │ error         [ ⚠ Try again               ]    │  ← data-state="error"
   │ success       [ ✓ Saved                   ]    │  ← data-state="success"
   │                                                │
   └────────────────────────────────────────────────┘
   ```

   Each labelled row uses a class (e.g. `.is-hover`) that the component's CSS targets in addition to the real pseudo-class, so all 8 states render at once on the demo page. Example:

   ```css

From victorhg/pi-dev, MIT.

More from victorhg/pi-dev