mirror of
https://github.com/Nutlope/hallmark.git
synced 2026-08-14 12:35:33 +02:00
Merge pull request #7 from Nutlope/trim-readme-roadmap
Docs · shorten README and ROADMAP
This commit is contained in:
Hassan El Mghari
@@ -10,27 +10,7 @@ Made by Together AI.
|
||||
<img src="site/OG-hallmark.png" alt="Hallmark — A design skill that refuses to look AI-generated" />
|
||||
</p>
|
||||
|
||||
Hallmark encodes the anti-AI-slop consensus — typography, colour, layout, motion, microinteractions, structural variety — into one opinionated rule-set. It picks a macrostructure for the brief, dresses it in one of twenty-two themes, runs sixty-five slop-test gates plus a pre-emit self-critique before handing back, and refuses the on-distribution defaults every LLM was trained into.
|
||||
|
||||
> **v1.0.0** — pre-emit critique on six axes, honest-copy enforcement, locked-token discipline, re-drawn-chrome ban, and a no-wrap rule for clickable text. Five new slop-test gates (56–60). The full rule-set lives in [`SKILL.md`](SKILL.md) and [`references/`](references/).
|
||||
|
||||
|
||||
---
|
||||
|
||||
## What's distinct — quick map vs the field
|
||||
|
||||
| | Hallmark | [frontend-design](https://github.com/anthropics/skills) (Anthropic) | [Open Design](https://github.com/nexu-io/open-design) | [Dembrandt](https://github.com/dembrandt/dembrandt) |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| **Source of taste** | extracts DNA from a screenshot OR a URL (`study` verb) — image mode names roles + candidates; URL mode names exact fonts + tokens | art-director brief + ban list | menu of 72 brand presets (Linear, Stripe, Vercel, Notion…) | scrapes a live URL, emits computed tokens |
|
||||
| **Output unit** | macrostructure + theme + custom-craft, optional portable `design.md` | bans + brief framing | preset application | DTCG `tokens.json` |
|
||||
| **Refuses font ID** | image mode: yes — names role only; URL mode: names what the page declares | n/a | n/a | n/a (computes from CSS) |
|
||||
| **Refuses pixel-clone** | yes — DNA only, never pixels (both modes) | n/a | n/a | n/a (full token export) |
|
||||
| **Refuses third-party extraction** | yes — paid templates / competitors / unrelated sites auto-refused; `design.md` emission has a tighter layer with URL-mode attestation | n/a | n/a | n/a (extracts anything) |
|
||||
| **Tactile-rebellion alignment** | warm-paper, custom-craft, slopless canon | strong | medium | none — token-only |
|
||||
| **Pages by archetype** | 21 named macrostructures, picked per brief | by brief | 5 deterministic directions | n/a |
|
||||
| **Verbs** | 4 (default · `audit` · `redesign` · `study`) | 1 | 31 | 1 (CLI) |
|
||||
|
||||
Hallmark's edge is **`study`** — every other tool ships a preset menu or a scraper. Hallmark is the only one that takes a screenshot *or* a URL of a design you admire, names what it sees (roles in image mode, exact fonts + tokens in URL mode), refuses paid-template-marketplace listings outright, and either rebuilds your content with the extracted DNA or emits a portable `design.md` you can hand to another AI tool — with a tighter refusal layer for the portable spec than for the diagnosis itself. Three worked study examples in [`docs/study-examples.md`](docs/study-examples.md).
|
||||
Hallmark picks a macrostructure for the brief, dresses it in one of twenty-two themes, runs sixty-five slop-test gates plus a pre-emit self-critique, and refuses the on-distribution defaults every LLM was trained into. Two pages by Hallmark for two different briefs feel like different sites, not colour-swaps of the same template.
|
||||
|
||||
---
|
||||
|
||||
@@ -38,16 +18,16 @@ Hallmark's edge is **`study`** — every other tool ships a preset menu or a scr
|
||||
|
||||
| Verb | What it does |
|
||||
| --- | --- |
|
||||
| *(default)* | Build new UI. Asks for audience + use + tone (skippable — the skill states what it inferred). Picks a macrostructure, applies the rule-set, runs the slop test before handing back. |
|
||||
| `hallmark audit <target>` | Score existing code against the named anti-patterns + structural sameness. Punch list, no edits. |
|
||||
| `hallmark redesign <target> [--mood <name>]` | Throw out the structure, keep copy + IA + brand, rebuild with a deliberately different fingerprint. |
|
||||
| **`hallmark study <screenshot \| URL>`** | The differentiator. Extract the **DNA** from a design the user admires — macrostructure, archetypes, type-pairing, colour anchor — and produce a diagnosis report. Accepts either an attached screenshot or a URL to a live page. After the diagnosis the user can optionally rebuild *their* content using the extracted DNA, **or** lock the DNA into a portable `design.md` other AI tools (Cursor, v0, Bolt) can read directly. **URL mode** reads HTML / CSS via WebFetch — names exact fonts and exact colour values, can't judge rhythm, and falls back to asking for a screenshot if the page is auth-walled or a JS-only shell. **Refuses paid templates and competitor pages. Image mode names font roles (never font IDs); URL mode names actual fonts (the page declares them). Never copies pixels. `design.md` emission has a tighter refusal layer than the diagnosis itself — URL-mode emission asks the user to attest the source is theirs or a public reference for their own brand.** |
|
||||
| *(default)* | Build new UI. Picks a macrostructure, applies the rule-set, runs the slop test before handing back. |
|
||||
| `hallmark audit <target>` | Score existing code against the anti-patterns. Punch list, no edits. |
|
||||
| `hallmark redesign <target>` | Throw out the structure, keep copy + IA + brand, rebuild with a different fingerprint. |
|
||||
| `hallmark study <screenshot \| URL>` | 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. |
|
||||
|
||||
---
|
||||
|
||||
## Different briefs, different shapes
|
||||
|
||||
A handful of examples below — each generated by exercising the skill on a different brief. The skill picks differently for every prompt; no two share a macrostructure or theme.
|
||||
Each generated by exercising the skill on a different brief. The skill picks differently every time — no two share a macrostructure or theme.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
@@ -57,10 +37,10 @@ A handful of examples below — each generated by exercising the skill on a diff
|
||||
<td width="25%"><a href="https://www.usehallmark.com/examples/bananastudio/"><img src="docs/screenshots/hero-bananastudio.jpg" alt="BananaStudio creative studio hero" /></a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Tally</b><br/><sub>SaaS product page · modern-minimal</sub></td>
|
||||
<td><b>Wayfare</b><br/><sub>Travel booking · atmospheric</sub></td>
|
||||
<td><b>Slow Pour</b><br/><sub>Small-batch coffee subscription</sub></td>
|
||||
<td><b>BananaStudio</b><br/><sub>Creative studio · playful motion</sub></td>
|
||||
<td><b>Tally</b><br/><sub>SaaS · modern-minimal</sub></td>
|
||||
<td><b>Wayfare</b><br/><sub>Travel · atmospheric</sub></td>
|
||||
<td><b>Slow Pour</b><br/><sub>Coffee subscription</sub></td>
|
||||
<td><b>BananaStudio</b><br/><sub>Studio · playful</sub></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="https://www.usehallmark.com/_tests/06-anya-portfolio/"><img src="docs/screenshots/hero-anya.jpg" alt="Anya Reis personal site hero" /></a></td>
|
||||
@@ -69,44 +49,14 @@ A handful of examples below — each generated by exercising the skill on a diff
|
||||
<td><a href="https://www.usehallmark.com/examples/hyperlane/"><img src="docs/screenshots/hero-hyperlane.jpg" alt="Hyperlane developer infrastructure hero" /></a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Anya Reis</b><br/><sub>Software architect personal site</sub></td>
|
||||
<td><b>NAJM</b><br/><sub>Moroccan fashion brand</sub></td>
|
||||
<td><b>Søroe</b><br/><sub>Small ceramics studio</sub></td>
|
||||
<td><b>Hyperlane</b><br/><sub>Developer infrastructure</sub></td>
|
||||
<td><b>Anya Reis</b><br/><sub>Personal site</sub></td>
|
||||
<td><b>NAJM</b><br/><sub>Fashion brand</sub></td>
|
||||
<td><b>Søroe</b><br/><sub>Ceramics studio</sub></td>
|
||||
<td><b>Hyperlane</b><br/><sub>Dev infrastructure</sub></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Each page is its own self-contained HTML + CSS — no shared theme, no shared layout. Every one carries a `/* Hallmark · macrostructure: … */` stamp at the top of its CSS. See the full set under [`site/_tests/`](site/_tests/) or live at [www.usehallmark.com](https://www.usehallmark.com).
|
||||
|
||||
---
|
||||
|
||||
## What's inside
|
||||
|
||||
- **[`SKILL.md`](SKILL.md)** — the routing file. Six-step design flow (including `Step 2.5 · Check project memory` reading `.hallmark/log.json`), 65-gate slop test, output contract, always-on `tokens.css` export.
|
||||
- **[`references/`](references/)** — short, opinionated rule files: typography, colour, layout, motion, microinteractions, interaction-and-states (with the input-state checklist), responsive, copy, anti-patterns, the 21 named macrostructures, the **40 component archetypes** with variation knobs (9 hero · 6 feature · 4 CTA · 4 testimonial · **8 footer · 9 nav**), the **4 hero polish patterns** (in `hero-enrichment.md`), the 6 primitive structure axes, the vision-extraction protocol for `study`, hero enrichment, custom-craft (CSS art over Lottie), assets, the slop-test gates, four genre rule-overlays (each with nav + footer voice routing), per-verb dispatchers, and the export-formats reference (Tailwind / DTCG / shadcn / tokens.css).
|
||||
- **[`docs/`](docs/)** — human-reading content: **[`recipes.md`](docs/recipes.md)** (8 worked briefs + a canonical try-it prompt) and **[`study-examples.md`](docs/study-examples.md)** (3 worked DNA-extractions). Not auto-loaded by the skill.
|
||||
- **[`site/`](site/)** — a self-demonstrating landing page. Hand-written HTML + CSS + ES module, no framework, no build step. **Twenty-two themes** clustered into four genres: **editorial** (Specimen, Editorial, Atelier, Newsprint, Salon, Linen, Almanac, Garden, Studio, Sport, Riso, Brutal, Manifesto), **modern-minimal** (Quiet, Coral, Violet), **atmospheric** (Midnight, Terminal, Bloom, Aurora, Halo), **playful** (Plume). Switching themes literally rebuilds the page — different hero archetype, different footer archetype, different nav archetype.
|
||||
|
||||
---
|
||||
|
||||
## What's distinct (the long list)
|
||||
|
||||
- **One skill, four verbs.** Not eighteen commands.
|
||||
- **Genres broaden the range.** Hallmark routes a brief through one of four genres before picking a theme: **editorial** (default · the canonical anti-slop voice), **modern-minimal** (Stripe / Linear / ElevenLabs school), **atmospheric** (Suno / Runway / dark-AI-tool school), **playful** (post-Linear soft school). Each genre is its own rule overlay — atmospheric allows radial blooms; modern-minimal allows pure white and pill CTAs; editorial bans both. Detection is signal-based, silent default to editorial.
|
||||
- **Tone is a first-class decision.** "Clean and modern" is rejected. Pick an extreme — *editorial · brutalist · soft · technical · luxury · playful · austere*.
|
||||
- **Macrostructures over axes.** Pick one of 21 named whole-page shapes wholesale; the macrostructure stamp lives in the CSS comment, so the next Hallmark run picks something different.
|
||||
- **Within-archetype variation.** Two Bento Grids should not be twins; each archetype has 2–3 picked-per-output knobs.
|
||||
- **Microinteractions as discipline.** Silent success over celebratory toasts. Optimistic update + Undo over confirm dialogs. Hover delay 800 ms, focus delay 0 ms.
|
||||
- **A 65-gate slop test** runs before every output. One yes fails the build. Recent additions: typography discipline gates (39–40: max three font families per page, outlier face used in ≤ 2 slots), input-state gates (41–45: no border-width layout shift, focus ring via outline not border, input height matches button height, helper-text slot reserves height, disabled state needs three independent signals), contrast gates (46–50: APCA / WCAG thresholds, accent-ink token requirement, dark-section ink-on-ink check), **nav · footer · hero structural gates (51–55: AI nav fingerprint, AI footer fingerprint, hero centred-everything, hero padding asymmetry, decorative-without-purpose)**, **honest-copy + chrome + token + responsive gates (56–60: invented metrics, re-drawn UI chrome, mid-render token improvisation, two-line clickable text, emoji-as-feature-icon)**, and **layout-safety gates (61–65: 1fr image-track overflow, missing `overflow-x: clip`, display-header word-break, theme section-head mobile collapse, CSS-only radio tabs scroll-jumping)**.
|
||||
- **Project memory.** A per-project `.hallmark/log.json` records each run's macrostructure + theme + enrichment + brief summary. The skill reads the last 3–5 entries before picking and writes a new entry after each build, so consecutive Hallmark outputs in the same project don't repeat shapes or themes.
|
||||
- **Theme-diversification rule.** Two consecutive themes must differ on at least one of three axes: paper band (dark / mid / light), display style (italic-serif / roman-serif / geometric-sans / mono / display-heavy / system-native), accent hue (warm / cool / neutral / chromatic-other).
|
||||
- **Voice fixtures over LLM defaults.** Each of the 21 macrostructures ships with 2–3 example opening lines tuned to its tone. "Built for the modern team" is in the banned-phrases list.
|
||||
- **Hero enrichment is opt-in.** A typographic-only hero is always acceptable. When enrichment is right, the skill picks from a six-tier hierarchy: typography only → custom-built CSS art → hand-built SVG → generated illustration (Nanobanana / Recraft) → library → Lottie (last resort).
|
||||
- **Microinteractions default-on for SaaS-shaped archetypes.** Bento Grid, Stat-Led, Workbench, Marquee Hero pages ship with 2–3 purposeful microinteractions (number reveal, pricing lift, marquee, stagger) without the user having to ask. Editorial / Manifesto / Letter / Quote-Led pages stay still.
|
||||
- **SaaS page sequence.** Hero → social proof → features → testimonials → pricing → FAQ → CTA → footer. Real prices, not "contact sales for pricing." Specific testimonials with role + company.
|
||||
- **Wordmark may use a different display face.** A Geist-bodied SaaS page can set its wordmark in Fraunces. Same-family collapse on Bento / Stat-Led / Workbench / Marquee Hero is the new "un-branded" tell.
|
||||
- **`study` extracts DNA, not pixels.** Refusal heuristics, type-role vocabulary (no font ID guessing in image mode), confirmation step before any code. Accepts a screenshot *or* a URL — URL mode reads HTML / CSS via WebFetch and names exact fonts + exact tokens (trades the rhythm pass for accuracy on everything else), with a graceful screenshot fallback when the URL is auth-walled or a JS-only shell. Three worked examples in [`docs/study-examples.md`](docs/study-examples.md).
|
||||
- **Opt-in `design.md` lock-the-system flow — two entry points.** Iterate freely on the first builds; when the system is settled, say *"lock the system"* (or *"give me a design.md"*) and Hallmark extracts the build's tokens + voice into a portable design system at the project root. **Or**, after a `study` diagnosis, say *"lock the DNA"* and Hallmark emits the same `design.md` format seeded from the studied source — URL mode populates exact tokens + fonts; image mode populates estimated bands + candidate fonts. From that point on every Hallmark run defers to the file, the diversification rule inverts to consistency, and the file becomes the single source of truth for scaling the design across a real app. The study-mode emission carries a tighter refusal layer than the diagnosis itself — third-party URLs require user attestation (your own site / public reference for your own brand), competitors and paid templates are auto-refused. Phrase-triggered from either entry point, never auto-emitted. See [`references/design-md.md`](references/design-md.md).
|
||||
Each page is self-contained HTML + CSS, stamped with its macrostructure in the CSS comment. Browse the full set at [usehallmark.com](https://www.usehallmark.com) or under [`site/_tests/`](site/_tests/).
|
||||
|
||||
---
|
||||
|
||||
@@ -116,29 +66,13 @@ Each page is its own self-contained HTML + CSS — no shared theme, no shared la
|
||||
npx skills add nutlope/hallmark
|
||||
```
|
||||
|
||||
Or copy [`SKILL.md`](SKILL.md) + [`references/`](references/) into one of:
|
||||
Re-run any time to update. Or copy [`SKILL.md`](SKILL.md) + [`references/`](references/) into:
|
||||
|
||||
- **Claude Code** — `~/.claude/skills/hallmark/`
|
||||
- **Cursor** — `.cursor/rules/hallmark.mdc` (body of `SKILL.md`, no frontmatter)
|
||||
- **Codex** — `~/.codex/skills/hallmark/` (personal, all projects) or `.codex/skills/hallmark/` (project-scoped, commit to repo)
|
||||
- **Codex** — `~/.codex/skills/hallmark/` (personal) or `.codex/skills/hallmark/` (project-scoped)
|
||||
|
||||
## Updating
|
||||
|
||||
```
|
||||
npx skills add nutlope/hallmark
|
||||
```
|
||||
|
||||
Re-run any time to pull the latest. If the CLI complains the skill already exists, delete the install path first (`~/.claude/skills/hallmark/` on Claude Code, or `.agents/skills/hallmark/` if you ran `skills add` from a project directory) and re-run.
|
||||
|
||||
To preview the landing page locally:
|
||||
|
||||
```
|
||||
cd site && python3 -m http.server 4173 # → http://localhost:4173
|
||||
```
|
||||
|
||||
Press `T` to cycle themes, the **shuffle button** (or `R`) to randomise, `?theme=studio` for a shareable link.
|
||||
|
||||
Or visit the live deploy at **[www.usehallmark.com](https://www.usehallmark.com)**.
|
||||
The rule-set lives in [`SKILL.md`](SKILL.md) and [`references/`](references/). Worked examples in [`docs/recipes.md`](docs/recipes.md) and [`docs/study-examples.md`](docs/study-examples.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
+20
-180
@@ -1,201 +1,41 @@
|
||||
# Hallmark — Roadmap
|
||||
# Roadmap
|
||||
|
||||
A forward-looking plan for what to build next, drawn from the gaps the latest research surfaced and from where the field is heading. Ordered by impact-to-effort.
|
||||
What's next.
|
||||
|
||||
---
|
||||
|
||||
## Now — actively working on
|
||||
## Now
|
||||
|
||||
### N.1 Better themes + more custom-designed themes
|
||||
**Tighten the 22-theme catalog.** A handful of themes (Plain, Specimen, Salon, Linen) bleed into each other on first read — same paper-band, similar accent footprint, similar display role. Audit each theme's three diversification axes (paper-band / display-style / accent-hue), pull overlapping pairs apart, and add 4–6 new themes in underserved corners (mid-band warm chromatic, dark-monochrome editorial, high-contrast print-poster, warm dark with handwritten accent). Each new theme ships with its own tokens block and stamp axis.
|
||||
|
||||
**Status now.** The 22 catalog themes work but a handful (Plain, Specimen, Salon, Linen) bleed into each other on first read — same paper-band, similar accent footprint, similar display roles. Real distinctiveness lives in only ~12 of them. Custom-theme construction (the `custom-theme.md` branch) exists but is rarely reached for; users mostly stay on catalog defaults.
|
||||
|
||||
**Build.**
|
||||
1. **Tighten the existing 22** — audit each theme's three diversification axes (paper-band / display-style / accent-hue) and pull any pair that overlaps on 2+ axes back to distinct territory. The themes that ship today should each carry a stronger fingerprint.
|
||||
2. **Add 4–6 new catalog themes** in underserved corners of the axis space — e.g. mid-band warm chromatic (something between Salon and Garden), dark-monochrome editorial (no current Midnight equivalent for serif-led editorial), high-contrast print-poster (a Brutal cousin that's quieter), warm dark with handwritten accent. Each new theme ships with its own tokens block in `site/css/tokens.css` and a stamp axis declaration.
|
||||
3. **Surface the custom branch more often.** Right now custom requires 3+ vibe words. Lower the bar so a single distinctive brand colour or unusual font request routes to custom, not the closest catalog cousin.
|
||||
|
||||
**Why it matters.** Catalog rotation is the headline differentiator — if half the catalog is interchangeable, the rotation doesn't deliver. More distinct themes = more visible variety per session = users feel the discipline working without reading the rules.
|
||||
|
||||
### N.2 Nanobanana image generation inside Hallmark (image-led theme)
|
||||
|
||||
**Status now.** [`assets.md`](references/assets.md) lists Nanobanana as the canonical generated-still source (Tier C in the enrichment hierarchy) but the integration is *recommend-only* — Hallmark tells the user to go generate something and bring it back. No first-class image-led theme exists; image-heavy briefs route to a typography-only macrostructure and feel underserved.
|
||||
|
||||
**Build.**
|
||||
1. **First-class Nanobanana hook.** When the brief signals "needs imagery" (e-commerce, travel, food, lookbook, gallery) and the user hasn't supplied real assets, Hallmark generates a brief for Nanobanana (style, subject, framing, palette tokens), invokes the API, ingests the returned image, and wires it into the build. Cache by prompt hash so re-runs are cheap.
|
||||
2. **New image-led theme** (working title: **Plate**) — a theme tuned for image-heavy compositions. Generous photographic framing, neutral chrome around full-bleed imagery, hairline rules, restrained type so the picture leads. Pairs with the Photographic macrostructure and the H6 Photographic-Fold archetype. Distinct from existing themes because it assumes imagery exists and treats text as caption-grade.
|
||||
3. **Token discipline for generated stills.** Nanobanana outputs need to thread back to the theme's accent / paper — extract dominant hue from the returned image, suggest as accent override, let the user confirm. Prevents the "generated image clashes with the theme palette" failure mode.
|
||||
|
||||
**Why it matters.** Today Hallmark is a typography-led tool. Half of real-world landing pages need imagery (consumer brands, hospitality, e-commerce). Adding first-class Nanobanana support + an image-led theme covers that gap without forcing the user to leave the skill, and it positions Hallmark as a complete builder rather than a type-only specialist.
|
||||
**Nanobanana hook for image-heavy briefs.** Today the integration is recommend-only — Hallmark tells the user to go generate something and bring it back. Image-heavy briefs (e-commerce, travel, food, lookbook) route to typography-only and feel underserved. Add a first-class hook that writes a prompt, invokes the API, ingests the returned image, and wires it into the build (cache by prompt hash). Pair with a new image-led theme (working title *Plate*) tuned for full-bleed photographic compositions.
|
||||
|
||||
---
|
||||
|
||||
## Tier 1 — Ship next (high impact, contained scope)
|
||||
## Next
|
||||
|
||||
### 1.1 Theme-aware microinteraction tokens
|
||||
**Brand-first flow.** From a short product description, Hallmark generates a complete brand — palette, type system, voice, custom imagery via Nanobanana — and locks it into a `design.md`. The user then runs Hallmark normally and the whole site builds against that generated brand, page after page. Closes the gap for users who have a product idea but no brand yet.
|
||||
|
||||
**Status now.** [`microinteractions.md`](references/microinteractions.md) describes a duration multiplier per theme as a table — but the multipliers aren't actually expressed in CSS. Atelier and Salon should *feel* slower than Brutal and Sport, but right now they share the same `--dur-short` / `--dur-long`.
|
||||
**Theme-aware motion tokens.** Per-theme `--dur-micro` / `--dur-short` / `--dur-long`, scaled by the table already in [`microinteractions.md`](references/microinteractions.md). Atelier should feel slower than Brutal; today they share durations. One pass through the tokens file.
|
||||
|
||||
**Build.** Move `--dur-micro`, `--dur-short`, `--dur-long` into per-theme overrides in [`tokens.css`](site/css/tokens.css), scaled by the table in `microinteractions.md`. Newsprint and Terminal use `0ms` for spatial motion (they're print/terminal metaphors). One pass through the file; small diff.
|
||||
**`hallmark variant`** — produce three structurally distinct versions of the same brief side-by-side; the user picks one or asks for a fourth. The biggest cause of "AI feel" is users accepting the first output because they didn't know it could be different.
|
||||
|
||||
**Why it matters.** Today a Salon page and a Brutal page animate at the same speed. They shouldn't. The principle of structural variety should extend to motion variety.
|
||||
**Structural cookbook.** [`structure.md`](references/structure.md) catalogues the *axes* of variety but doesn't show what a left-margin-headed, hairline-divided, no-image page actually looks like assembled. Twelve to twenty worked fingerprints with short HTML/CSS sketches — patterns are easier to reach for than principles.
|
||||
|
||||
### 1.2 DESIGN.md output protocol
|
||||
**Tactile-rebellion reference.** Controlled imperfection — handmade textures, hand-drawn SVG paths, controlled-jitter typography (a 0.5° tilt on one mark is taste; on every word it's chaos). Where the field is going.
|
||||
|
||||
**Status now.** Hallmark produces code. It does not produce a portable design spec.
|
||||
**Charts reference for analytics pages.** AI-generated charts are an obvious tell — rainbow palettes, dense gridlines, 3D donuts, dual-axis line spaghetti. Add a `data-viz.md` that picks small multiples over single dense charts, restrains colour to one accent + neutrals, and bans the worst types outright. Half of every dashboard is chart-shaped, and Hallmark currently has nothing to say about it.
|
||||
|
||||
**Build.** When Hallmark generates new work, also emit a `DESIGN.md` in the project root containing: chosen tone, palette tokens (with OKLCH values), type stack, spacing scale, structural fingerprint, motion tokens, and the named anti-patterns the page must continue to avoid. Other AI tools (Cursor, v0, Bolt) can read this file directly to keep iterating on the same design language.
|
||||
**Multi-page coherence.** The structural-variety rule is correct for variety, wrong for brand consistency inside a multi-page product. Lock the brand axes (type, colour, divider language); vary the page-voice axes (heading placement, body composition, button voice). Different *pages* of the same site, not different *sites*.
|
||||
|
||||
**Why it matters.** Closes the loop between Hallmark and the rest of the agent ecosystem. The skill stops being a one-shot generator and becomes a system that hands its decisions forward.
|
||||
|
||||
### 1.3 `hallmark variant` — three fingerprints, user picks one
|
||||
|
||||
**Status now.** Hallmark produces *one* designed output per brief.
|
||||
|
||||
**Build.** New verb: `hallmark variant <target>` produces three structurally distinct versions of the same brief — different fingerprints across the six axes — and presents them as a side-by-side comparison. The user picks the one that fits, or asks for a fourth. This is the workflow `taste-skill v3.0` parameterises with dials; Hallmark would expose it as a verb.
|
||||
|
||||
**Why it matters.** The biggest cause of "AI feel" isn't bad output — it's the user accepting the *first* output because they don't know it could be different. Showing three forces a judgement call and surfaces taste.
|
||||
|
||||
### 1.4 Theme switcher polish on the landing page
|
||||
|
||||
**Status now.** The 12-theme picker is good but a few rough edges remain.
|
||||
|
||||
**Build.**
|
||||
- Trap the focus inside the popover when open (currently focus can escape).
|
||||
- Make the swatch dots match each theme's *exact* paper/ink/accent (some currently approximate).
|
||||
- On theme apply, briefly flash the orange accent rule under the trigger label to confirm — *silent success* via a 200ms colour pulse, not a toast.
|
||||
- The kbd hint (`press T`) currently sits next to the trigger but only on hover — also reveal on `:focus-within` of the navbar, for keyboard users who haven't reached for the mouse.
|
||||
|
||||
**Why it matters.** The landing page itself is the strongest demo of Hallmark's microinteraction taste. It has to be exemplary.
|
||||
**`study` reads your own codebase too.** Today `study` accepts a screenshot or a URL of an external design. Add a third input mode: a path to your project. Hallmark walks the files, identifies tokens + the structural fingerprint actually in use, and emits the same `design.md`. Closes the loop for users who arrive with code, not a brief — same verb, same output, third input mode.
|
||||
|
||||
---
|
||||
|
||||
## Tier 2 — Build after Tier 1 lands (still concrete, more scope)
|
||||
## Later
|
||||
|
||||
### 2.1 `references/structural-cookbook.md` — concrete recipes
|
||||
|
||||
**Status now.** [`structure.md`](references/structure.md) catalogues the *axes* of structural variety. It doesn't show *what* a left-margin-headed, single-column, hairline-divided, unstyled-link, no-image, no-reveal page actually looks like assembled.
|
||||
|
||||
**Build.** A cookbook file with 12–20 *complete* structural fingerprints, each with a short HTML/CSS sketch, a paragraph explaining when to reach for it, and a real-world reference (NYT Mag, Stripe, Linear, Pentagram, etc.). The cookbook teaches the model patterns the same way recipe books teach cooking — through *worked examples*, not just *principles*.
|
||||
|
||||
**Why it matters.** Models are pattern-matchers. Catalogued patterns + named recipes are easier to reach for than principles + axes.
|
||||
|
||||
### 2.2 `references/tactile-rebellion.md` — controlled imperfection
|
||||
|
||||
**Status now.** Hallmark assumes pixel-precision is the goal. The 2026 cultural movement is the opposite: handmade textures, controlled imperfection, *wabi-sabi*. 73% of designers (per CreativeBloq's 2026 trends report) are deliberately adding imperfections to differentiate from AI.
|
||||
|
||||
**Build.** A new reference file covering: when to apply texture (sparingly; one element per page max); how to do it without falling into kitsch (real letterpress reference, not "letterpress filter"); free SVG noise/grain generators; hand-drawn SVG path techniques; controlled-jitter typography (a 0.5° rotation on a single mark is taste; on every word it's chaos).
|
||||
|
||||
**Why it matters.** This is where the field is going and the current canon (impeccable, kami) has nothing on it. First-mover advantage.
|
||||
|
||||
### 2.3 `references/data-viz.md` — Tufte-leaning anti-slop charts
|
||||
|
||||
**Status now.** Nothing about charts. Yet a dashboard or analytics page is half data viz, and AI-generated charts are *especially* bad — rainbow palettes, 3D pies, gridlines everywhere, sparkles instead of lines.
|
||||
|
||||
**Build.** A reference file covering: small multiples over single dense charts; tabular numbers; restraint in colour (one accent for the focal series, neutrals for context); axis design (minimum gridlines, no chartjunk); when to use bars vs lines vs sparklines; banned chart types (3D anything, donut charts where pie would do, dual-axis line charts).
|
||||
|
||||
**Why it matters.** Data-density is the next frontier of "looks AI-generated" — and Tufte is the canonical reference no current skill cites.
|
||||
|
||||
### 2.4 Multi-page coherence rules
|
||||
|
||||
**Status now.** Hallmark's structural-variety rule says "two consecutive pages in the same session should not share more than three of the six structural axes." That's correct for variety but wrong for *brand consistency* across a real product where every page should feel like the same site.
|
||||
|
||||
**Build.** A new reference: `references/coherence.md`. When working within a multi-page project, lock the first three axes (typography, colour, divider language — the *brand* axes) and vary the remaining three (heading placement, body composition, button voice — the *page-voice* axes). Different *pages* of the same site, not different *sites*. Add a test: "if I removed the navigation, would these two pages look like they're from the same product?" Yes. Continue. No. Re-anchor.
|
||||
|
||||
**Why it matters.** Right now the structural-variety rule is too strong. Real products need *coherent variety*, not chaotic variety.
|
||||
|
||||
### 2.5 `hallmark extract` — read existing code, output DESIGN.md
|
||||
|
||||
**Status now.** Hallmark generates from briefs. It can't ingest existing systems.
|
||||
|
||||
**Build.** New verb: `hallmark extract <directory>`. Reads the codebase. Identifies tokens (colour vars, type ramps, spacing scale, easings). Identifies the structural fingerprint actually in use. Writes a DESIGN.md the user can hand to other agents — or to Hallmark itself for `redesign` work. SkillUI does this for visual designs; Hallmark would do it taste-aware.
|
||||
|
||||
**Why it matters.** Most users come to Hallmark *with* an existing codebase, not a greenfield brief. The skill needs an entry point for the existing case.
|
||||
|
||||
---
|
||||
|
||||
## Tier 3 — Long horizon (research-grade, ambitious)
|
||||
|
||||
### 3.1 `hallmark explain` — pedagogy verb
|
||||
|
||||
A verb that explains the choices made, *axis by axis*, in plain language. "I picked left-margin headings because the brief was editorial and the audience is reading-led; I picked hairline dividers because the tone was austere and ornament would have warmed the page; I picked silent success on the form because the user can see the row was saved." Teaches users to make the same choices themselves over time. The skill becomes a *teacher*, not just a generator.
|
||||
|
||||
### 3.2 Negative-capability rules
|
||||
|
||||
[PencilPlaybook](https://github.com/stevembarclay/pencilplaybook) embeds *perceptual psychology* in its anti-patterns — not just "don't use side-stripe cards" but "side-stripe cards trigger a horizontal cognitive scan that splits the user's attention from the content; the brain has to process two reading axes at once, which costs ~120ms per card." That's a different kind of teaching.
|
||||
|
||||
Build a `references/why.md` that, for each major anti-pattern, includes the perceptual or cognitive reason it fails. Models that *understand* an anti-pattern reach for the alternative more reliably than models that just *know* the anti-pattern.
|
||||
|
||||
### 3.3 Emotion-first prompting
|
||||
|
||||
Today: tone words (editorial, brutalist, austere). Tomorrow: emotion words (anxious, optimistic, nostalgic, sceptical). The brief "build me a page that feels nostalgic but also forward-looking" should produce different work than "build me a page that feels confident and warm" — even if the audience and use case are the same.
|
||||
|
||||
This requires a new mapping: emotion → tone → fingerprint. Worth building once the field has converged on what these mappings are. (Currently nobody has mapped them.)
|
||||
|
||||
### 3.4 Sound and haptic policy
|
||||
|
||||
Currently [`microinteractions.md`](references/microinteractions.md) says "no sound on web" — correct default. But Hallmark could ship a tiny module covering: when sound is appropriate (gaming, AAA brands, accessibility-augmenting); haptic feedback (Vibration API on mobile); and how to do them without crossing into kitsch. Small file; long horizon.
|
||||
|
||||
### 3.5 Live preview as a Claude Code MCP server
|
||||
|
||||
The most ambitious direction. Today Hallmark writes code into files; the user runs a static server to preview. A Claude Code MCP server could:
|
||||
- Watch the file
|
||||
- Render it in a sandbox
|
||||
- Take a screenshot
|
||||
- Feed the screenshot back to the model for self-critique against the slop test
|
||||
- Iterate
|
||||
|
||||
This closes the loop between *generation* and *audit*, automatically. The skill audits itself before handing back. Anthropic's [canvas-design](https://github.com/anthropics/skills) skill is a step toward this for static art; Hallmark could be the interactive equivalent.
|
||||
|
||||
---
|
||||
|
||||
## Things to *not* do
|
||||
|
||||
A list of tempting directions that would make Hallmark worse, not better. Forcing the discipline.
|
||||
|
||||
- **Don't add a fifth verb** before the existing four are battle-tested. `default / audit / refine / redesign` is enough surface area for the next six months. Adding `polish / typeset / colorize / animate / ...` (impeccable's path) trades comprehensibility for surface area. Resist.
|
||||
- **Don't add more than 12 themes.** The cognitive cost of 16 themes is higher than the value of 16 themes. If anything, *cut* underperforming ones.
|
||||
- **Don't ship a UI library.** Hallmark is a *taste* skill, not a component kit. shadcn/ui and Geist exist; refer users to them. Building components inside Hallmark dilutes the focus.
|
||||
- **Don't add A/B testing or analytics** to the skill. It's not a SaaS product.
|
||||
- **Don't build a Figma plugin.** The skill works in code; that's a feature, not a limit. Designers who want Figma have other tools.
|
||||
- **Don't add prompts to "match a brand"** by URL scraping on the *default* verb. That's SkillUI's job — point users there. **Exception:** `hallmark study` accepts URLs as a source for DNA extraction (read-only; never to clone the surface). The same refusal heuristics that govern image-mode `study` apply — marketplaces, template demos, and disclosed competitors are auto-refused before WebFetch fires.
|
||||
- **Don't add image generation.** Out of scope; AI imagery is its own problem space, and the right answer is usually "use real photos" or "no image."
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
How we know Hallmark is getting better, not just bigger:
|
||||
|
||||
1. **Slop test pass rate.** Every output should pass all 20 questions. Track failures and categorise.
|
||||
2. **Structural-fingerprint diversity.** Across the last 10 outputs of the skill, how many *unique* fingerprints? Target ≥ 8/10.
|
||||
3. **Microinteraction tells per output.** Target 0. (`transition-all`, `hover:scale-105`, bouncy easing on UI, etc. are flagged.)
|
||||
4. **User picks the first output without revision.** A high "first try" rate is the single best taste indicator. Track it.
|
||||
5. **DESIGN.md re-import round-trip.** A user runs `hallmark extract` then `hallmark` with the extracted DESIGN.md in scope. The result should match the original within token boundaries. If it drifts, the extraction or the application is wrong.
|
||||
|
||||
---
|
||||
|
||||
## What's already shipped
|
||||
|
||||
For reference. Everything below is in current `0.4.0`.
|
||||
|
||||
- ✓ Skill: 5 verbs (default, audit, refine, redesign, study)
|
||||
- ✓ References: typography, color, layout-and-space, motion, microinteractions, structure, interaction-and-states, responsive, copy, anti-patterns, macrostructures, component-cookbook, study, hero-enrichment, custom-craft, assets
|
||||
- ✓ 16 themes with structural fingerprints (including Studio, Pastel, Riso, Quiet)
|
||||
- ✓ 21 named macrostructures + 36 component archetypes with within-archetype variation knobs
|
||||
- ✓ Sticky-top banner theme picker with random + ?theme= URL parameter
|
||||
- ✓ Per-theme component archetype swap (hero + footer rebuild on theme change)
|
||||
- ✓ Hero enrichment: demo video / mockup / illustration / abstract background, with Lottie demoted to last resort
|
||||
- ✓ Custom-craft canon: pure CSS art, hand-built SVG, declarative animation, View Transitions, Three.js when justified
|
||||
- ✓ Asset-source catalogue: Lucide / Phosphor / Heroicons (icons), Simple Icons / SVGL (logos), Nanobanana 2 / Recraft V4 (generated illustration), Storyset / Humaaans (library), Mixkit / Coverr (video), Unsplash / Nappy (photography)
|
||||
- ✓ Working install path: `cp skill/* ~/.claude/skills/hallmark/`
|
||||
- ✓ Slop test 33 questions: visual (8), structural (2), microinteractions (10), variety (3), implementation (6), hero enrichment (4)
|
||||
- ✓ View Transitions on theme switch, with reduced-motion fallback
|
||||
- ✓ Copy-to-clipboard with silent success on install code blocks
|
||||
- ✓ Keyboard shortcut (`T` cycle, `Shift+T` reverse, `R` random)
|
||||
|
||||
---
|
||||
|
||||
## Deferred
|
||||
|
||||
- **Tier 2.3 — Data-viz / chart canon.** Small multiples, axis restraint, banned types (3D donut, dual-axis), Tufte principles. Mentioned in hero-enrichment.md but full reference not yet written.
|
||||
- **`hallmark explain`** — narrate the choices axis by axis. The skill teaches; users start making the same calls themselves.
|
||||
- **Negative-capability rules** — for each anti-pattern, the perceptual or cognitive reason it fails. Understanding it beats knowing it.
|
||||
- **Emotion-first prompting** — *nostalgic · optimistic · sceptical* instead of *editorial · brutalist · austere*. Today's tone words don't reach.
|
||||
- **Sound + haptic policy** — when web sound is acceptable (gaming, accessibility-augmenting) without crossing into kitsch.
|
||||
- **Live preview as an MCP server** — watch the file, render in a sandbox, screenshot, feed the screenshot back for self-critique against the slop test. Closes the loop between generation and audit.
|
||||
|
||||
@@ -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 <target>` | Read the target, score it against the anti-pattern list, return a ranked punch list. **Do not edit.** |
|
||||
| `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 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 <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. |
|
||||
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
+8
-10
@@ -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": "<the URL if source_mode=url, else null>",
|
||||
"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": "<name from macrostructures.md>",
|
||||
"macrostructure_alt":"<second-closest, if it leans>",
|
||||
"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 `<URL>` as a public reference for the user's brand on <date>. 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
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 MiB After Width: | Height: | Size: 621 KiB |
@@ -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.**
|
||||
|
||||
@@ -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.
|
||||
|
||||
+2
-2
@@ -18,8 +18,8 @@
|
||||
<meta property="og:image" content="https://www.usehallmark.com/OG-hallmark.png" />
|
||||
<meta property="og:image:secure_url" content="https://www.usehallmark.com/OG-hallmark.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="4800" />
|
||||
<meta property="og:image:height" content="2520" />
|
||||
<meta property="og:image:width" content="2400" />
|
||||
<meta property="og:image:height" content="1356" />
|
||||
<meta property="og:image:alt" content="Hallmark — A design skill that refuses to look AI-generated" />
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:title" content="Hallmark — A design skill that refuses to look AI-generated" />
|
||||
|
||||
Reference in New Issue
Block a user