Author/validate/export Google's DESIGN.md token spec files. Includes a verified data-sources table for design-system evidence, a working rules-engine (Dieter Rams' Ten Principles) that scores HTML output against named design principles to catch AI-taste, AND a two-scorer pattern (8-dim rubric + LLM holistic 0-100) validated on 12 paired contrastive samples. Exports DPO training format. Also includes the 6 golden rules for anti-AI-taste HTML (verified +10.6/16 8-dim delta, +70.4/100 LLM delta).
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Author/validate/export Google's DESIGN.md token spec files. Includes a verified data-sources table for design-system evidence, a working rules-engine (Dieter Rams' Ten Principles) that scores HTML output against named design principles to catch AI-taste, AND a two-scorer pattern (8-dim rubric + LLM holistic 0-100) validated on 12 paired contrastive samples. Exports DPO training format. Also includes the 6 golden rules for anti-AI-taste HTML (verified +10.6/16 8-dim delta, +70.4/100 LLM delta).
DESIGN.md is Google's open spec (Apache-2.0, google-labs-code/design.md) for
describing a visual identity to coding agents. One file combines:
YAML front matter โ machine-readable design tokens (normative values)
Markdown body โ human-readable rationale, organized into canonical sections
Tokens give exact values. Prose tells agents why those values exist and how to
apply them. The CLI (npx @google/design.md) lints structure + WCAG contrast,
diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON.
When to use this skill
User asks for a DESIGN.md file, design tokens, or a design system spec
User wants consistent UI/brand across multiple projects or tools
User pastes an existing DESIGN.md and asks to lint, diff, export, or extend
User wants to port a style guide into a format agents can consume
User wants contrast / WCAG accessibility validation on their color palette
User is fighting "AI-taste" in LLM-generated output (same Inter font
everywhere, glassmorphism on every page, blue-purple gradients as default).
Pair the DESIGN.md with the two-scorer system under scripts/ โ
tokens alone don't prevent AI-defaults. See "Anti-AI-taste workflow"
below.
User wants to build a preference dataset (chosen vs rejected HTML
pairs) for DPO training or few-shot evaluation. Use the 12-pair
sample dataset under templates/sample-pair/ as the starting point.
For purely visual inspiration or layout examples, use popular-web-designs
instead. For process and taste when designing a one-off HTML artifact
from scratch (prototype, deck, landing page, component lab), use
claude-design. This skill is for the formal spec file itself,
plus the tooling ecosystem around it (scorers, DPO export, sample
libraries).
User preference: original library, not a clone
When the user asks about building a Curio-like system, they want an original
style library grounded in design history โ not a clone of Curio's 751 brand styles.
The anti-ai-style-library skill implements this: each style is a real design
movement (Bauhaus, Swiss, Brutalist, etc.) with DESIGN.md + reference HTML +
8-dim validation (must score โค4/16). This skill (design-md) provides the judgment
layer; anti-ai-style-library provides the content layer. See
references/curio-architecture-analysis.md for the full architecture analysis.
File anatomy
---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
primary: "#1A1C2E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
Architectural Minimalism meets Journalistic Gravitas...
Deep ink for headlines and core text.
"Boston Clay" โ the sole driver for interaction.
Public Sans for everything except small all-caps labels...
is the only high-emphasis action on a page...
object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation
see above
Component property whitelist: backgroundColor, textColor, typography,
rounded, padding, size, height, width. Variants (hover, active,
pressed) are separate component entries with related key names
(button-primary-hover), not nested.
Canonical section order
Sections are optional, but present ones MUST appear in this order. Duplicate
headings reject the file.
Overview (alias: Brand & Style)
Colors
Typography
Layout (alias: Layout & Spacing)
Elevation & Depth (alias: Elevation)
Shapes
Components
Do's and Don'ts
Unknown sections are preserved, not errored. Unknown token names are accepted
if the value type is valid. Unknown component properties produce a warning.
Workflow: authoring a new DESIGN.md
Ask the user (or infer) the brand tone, accent color, and typography
direction. If they provided a site, image, or vibe, translate it to the
token shape above.
Write DESIGN.md in their project root using write_file. Always
include name: and colors:; other sections optional but encouraged.
Use token references ({colors.primary}) in the components: section
instead of re-typing hex values. Keeps the palette single-source.
Lint it (see below). Fix any broken references or WCAG failures
before returning.
If the user has an existing project, also write Tailwind or DTCG
exports next to the file (tailwind.theme.json, tokens.json).
Workflow: lint / diff / export
The CLI is @google/design.md (Node). Use npx โ no global install needed.
# Validate structure + token references + WCAG contrast
npx -y @google/design.md lint DESIGN.md
# Compare two versions, fail on regression (exit 1 = regression)
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
# Export to Tailwind theme JSON
npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
# Export to W3C DTCG (Design Tokens Format Module) JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
# Print the spec itself โ useful when injecting into an agent prompt
npx -y @google/design.md spec --rules-only --format json
All commands accept - for stdin. lint returns exit 1 on errors. Use the
--format json flag and parse the output if you need to report findings
structurally.
Lint rule reference (what the 7 rules catch)
broken-ref (error) โ {colors.missing} points at a non-existent token
duplicate-section (error) โ same ## Heading appears twice
wcag-contrast (warning/info) โ component textColor vs backgroundColor
ratio against WCAG AA (4.5:1) and AAA (7:1)
unknown-component-property (warning) โ outside the whitelist above
When the user cares about accessibility, call this out explicitly in your
summary โ WCAG findings are the most load-bearing reason to use the CLI.
Anti-AI-taste workflow (DESIGN.md as rules + judgement)
A DESIGN.md with Inter/Roboto/12px-rounded/glassmorphism-blue is just
documented AI-default. To produce output an LLM couldn't generate by
default, pair the token spec with a judgement rules engine. Two
working scorers in this skill, used together:
Scorer
Output
Use for
Speed
scripts/dataset-scorer.py (8-dim rubric)
0-16 per dimension, transparent
CI smoke tests, debugging which feature caused the score, automated regression gates
<2s
scripts/llm-judge.py (holistic 0-100)
single number + reasoning
"Is this good enough to ship?", preference pair selection for DPO, holistic quality control
~5s heuristic / ~3s LLM
Do not replace one with the other. The 8-dim scorer tells you which
feature caused the score (font cliche, purple gradient, etc.). The LLM
judge tells you the overall verdict. Together they give signal AND
explainability. The 8-dim rubric catches surface AI-taste (literal
"Inter" substring, literal #667eea hex, literal emoji codepoints);
it CANNOT catch "combination pattern" โ the sentence "Welcome to the
Future, Experience next-generation AI-powered solutions" scores 0/2 on
every single one of the 8 dimensions individually yet reads as 100%
AI-tasting because of how the words combine. The LLM judge fixes this.
Verified capabilities and limits (2026-06-15, 12-pair dataset)
Pairs validated: article, dashboard, email, form, landing, login, modal,
nav, pricing, product, settings, slide. Each scenario has one
AI-taste HTML (purple gradient + Inter + glassmorphism + emoji) and
one anti-AI-taste HTML (a real historical movement: Bauhaus, Memphis,
Ukiyo-e, De Stijl, Brutalist, Art Deco, Swiss, Terminal, etc.).
โ Catches cliche fonts (Inter/Roboto/Lato/Open Sans/Helvetica Neue) by
parsing font-family declarations (NOT raw substring โ see Bug 1 in
references/llm-scoring-approach.md).
โ Catches temporal visual cliches (glassmorphism, neumorphism, heavy
gradients) with regex patterns. Note: regex must escape parens.
โ Distinguishes widget-class density from data-table density (Bug 2:
grid layouts count 0.5x, flex/inline-block count 1x, widget/card/btn
class count 1x).
โ Marketing-copy detection uses word stems + \b boundary, not
exact-string match (Bug 3: catches "Empowering" / "Revolutionary").
โ Works as a smoke test in CI; pipeline runs in <2s on a single HTML page.
โ Exports DPO training format (output/dpo_dataset.jsonl) with
system prompt + prompt + chosen/rejected + scenario + metadata.
โ LLM judge mode: with OPENROUTER_API_KEY set, calls claude-sonnet-4
in batched mode (8 pairs/request) for actual LLM evaluation.
โ LLM judge fallback: with no API key, deterministic 0-100 heuristic
still produces ~6.5x better delta than 8-dim rubric on the same dataset.
โ ๏ธ 8-dim mean delta saturates around +10/16. LLM mean delta is
+70/100. Use both โ different jobs.
โ ๏ธ Six of ten Rams principles implemented. The other four (thorough,
honest, environmentally friendly, understandable) need human review or
richer analysis.
โ ๏ธ placeholder_copy dimension is the weakest of the 8. Replace
with LLM judge for production-grade scoring. Don't try to add more
regex features to fix it โ that's the ceiling.
โ ๏ธ element_density is the dimension LLMs most often fail.
Hand-curated anti-AI samples score 0; LLM few-shot output
typically scores 2 because it generates "4 metric cards + 1 table
2 status sections". The fix lives in the prompt, not the rubric:
add "ๅๅฑๆๅค 1 ไธชๆฐๆฎๅบ + 1 ไธช่กจๆ ผ/ๅ่กจ" to the task section.
See references/iterative-refinement-log.md for the verified
5-step sequence.
Quick reference: 6 golden rules (anti-AI taste, condensed)
The shortest path to anti-AI-taste HTML. Any page satisfying all 6 scores 0-2/16 on the 8-dim rubric.
Font โ Ban Inter/Roboto/Lato/Helvetica Neue. Use IBM Plex, Akzidenz Grotesk, Charter, or a historical face matching the design movement.
Gradient โ Ban purple-blue gradients (#667eea, #764ba2, #8b5cf6). Use solid colors or very subtle tints.
Glassmorphism โ Ban backdrop-filter: blur(...). Replace with borders or offset shadows.
Border radius โ Ban uniform 12px/16px. Use 0px or differentiated radii per element type.
Emoji โ Ban emoji as icons. Use SVG icons or plain text.
Copy โ Ban "future / next-gen / empower / seamless / revolutionary". Use concrete, restrained language.
Verified result (2026-06-15, 12-pair dataset): hand-curated anti-AI samples satisfying all 6 score 0-2/16. LLM few-shot output with these 6 rules as system prompt scores 2/16 on dashboard (down from 9/16 without rules).
Verified metrics (2026-06-15, 12-scenario ร 2 = 24 HTML samples)
Metric
Value
Notes
8-dim rubric mean delta
+10.6/16
AI vs anti-AI, 12 pairs
LLM judge mean delta
+70.4/100
claude-sonnet-4 batched
Few-shot eval (dashboard)
2/16
1โ4 positive examples, element_density 2โ1
Design intent verification
100%
LLM explanations all match real historical movements
Curio-like system: architecture analysis and implementation paths
When the user asks "how to build something like designbycurio.com", this skill has already been through that analysis (2026-06-15). The full analysis is in references/curio-architecture-analysis.md. Key conclusions:
Curio's three-layer model: Library (751 DESIGN.md files) โ Discovery (metadata filters) โ Delivery (MCP server for AI agents). Our skill covers the judgment layer that Curio doesn't have.
Implementation path chosen (2026-06-15): Path A โ Original style library. The user explicitly chose to build an original design-movement library (not a Curio clone) as the anti-ai-style-library skill. That skill provides the content layer; this skill provides the judgment layer. Together they cover "what styles are available" + "how to judge them".
The style library now exists: The anti-ai-style-library skill is the content layer that pairs with this skill's judgment layer. It has 15,144 style seeds across 7 tiers (55 base movements ร regions ร media ร moods ร textures), with a perpetual cron generating 10 seeds every 3 minutes via iFlytek MaaS. Load it when the user wants to "apply a style" or "generate anti-AI-taste HTML in a specific design language."
Deployment note: The skill lives at ~/.hermes/skills/creative/design-md/ and is also copied to ~/wiki/skills/design-md/. These are independent copies โ update both when making changes.
24 HTML samples (12 scenarios ร AI/anti-AI) โ extend to 20+ scenarios
DPO format (12 pairs) โ real training needs 500+
Next steps:
Tune LLM judge (needs OPENROUTER_API_KEY)
Expand to 30+ scenarios
Feed LLM judge findings back into 8-dim rubric rules
DPO training (trl + A100)
Pitfalls
Don't nest component variants.button-primary.hover is wrong;
button-primary-hover as a sibling key is right.
Hex colors must be quoted strings. YAML will otherwise choke on # or
truncate values like #1A1C2E oddly.
Negative dimensions need quotes too.letterSpacing: -0.02em parses as
a YAML flow โ write letterSpacing: "-0.02em".
Section order is enforced. If the user gives you prose in a random order,
reorder it to match the canonical list before saving.
version: alpha is the current spec version (as of Apr 2026). The spec
is marked alpha โ watch for breaking changes.
Token references resolve by dotted path.{colors.primary} works;
{primary} does not.
Verify data sources before recommending them. If the user wants to build
a design system backed by real-world artifacts (museum collections, design
archives, font usage examples), test that the source actually responds
before listing it as available. MoMA's API is Cloudflare-blocked;
Cooper Hewitt needs a free token; Met Open Access works without one but
doesn't support filtering by designer. See
references/data-sources-for-design-systems.md for the verified status
table and a 30-second verification recipe.
Tokens alone don't stop AI-taste. Inter + Roboto + glassmorphism + 12px
radius + emoji icons is the LLM default output, regardless of what your
DESIGN.md says. Pair the spec with a rules engine (Rams' Ten Principles,
Norman/Nielsen heuristics, Tufte's data-ink ratio) that scores the output
against named principles. Working example in scripts/scanner.py.
Build the demo before describing it. When the user asks "can you show
me how this would work," write the code and run it first. Description-only
answers hide bugs (URL encoding, regex escaping, false-positive font
matches, false-positive density matches) that the running code exposes
immediately. A 30-line scanner that actually runs will reveal more than
a 300-line description.
Don't substring-search font-family content. Search the declaration
(font-family: 'Inter', sans-serif โ first token "Inter"). Raw substring
match on "Inter" in html.lower() hits "Experience" (substring "Inter").
See Bug 1 in references/llm-scoring-approach.md.
Don't count raw HTML element tags for "AI-tasting density". A Bauhaus
dashboard with 14 table-row elements is NOT AI-tasting โ it's data-dense
by design. Count widget-class occurrences + flex/inline-block displays,
give grid 0.5x weight. See Bug 2.
Don't exact-match marketing keywords. "Empowering" / "Revolutionary"
won't match "empower" in text or "revolutionary" in text if your list
has just "empower" / "revolutionary". Use word stems (innovat catches
innovation / innovative / innovating) + \b boundary. See Bug 3.
Don't shadow re with an inner import re. In Python, an inner
import re inside a function shadows the module-level re for any
code that runs after. Symptom: UnboundLocalError: local variable 're' referenced before assignment. Use import re as _re inside the
function. See Bug 4.
8-dim scorer is a gate, not a score. It discriminates
AI-taste from anti-AI-taste at ฮ โ +10/16, but cannot rank two
anti-AI samples against each other. The LLM judge or human review
is the only thing that ranks anti-AI quality. Reporting "score = 1"
and "score = 2" as quality differences is a misuse. See
references/iterative-refinement-log.md "The second-biggest finding".
Don't substring-search for class names in element density.
A clean LLM output that uses data-area / header / table-area
class names will trip a card|panel|box|header blacklist even
when it has only 1 data area and 1 table. The current rubric
blocks this; if you extend the rubric, count independent
data sections (e.g. by structural marker: large numeric values
in monospace, or section headers), not class name patterns.
Workflow: build a paired contrastive dataset (recommended path for new projects)
The single-file scanner above is fine for smoke-testing one HTML. For serious
work, build a paired contrastive dataset: for each scenario (dashboard,
landing, article, product, slide, marketing), keep two HTML files โ an
AI-taste one and an anti-AI-taste one. Then score the whole dataset at
once. This workflow scales: pairs become DPO training data, LLM few-shot
examples, and an in-context "what to avoid" reference.
Recommended order of operations (validated by the user 2026-06-15
against a 12-pair dataset):
Define the 8-dimension rubric first, before writing any HTML. See
references/ai-taste-8-dimensions.md. Each dimension is 0-2
(0 = none, 2 = severe), total 0-16. Define scoring rules (regexes,
thresholds) in the rubric, not in code โ keeps the scorer pure.
Pick 8-12 high-contrast scenarios. Dashboard, landing, article,
product is a strong starting set. Add login, form, modal, nav,
pricing, settings, email, slide once the rubric is stable. The
12-pair validated set (2026-06-15) covers all common UI jobs.
Author pairs manually. Per scenario, write samples/{scenario}/ai/
(over-leverage the rubric's high-score features) and
samples/{scenario}/anti/ (use a real historical design movement โ
Bauhaus 1919, Memphis 1981, Ukiyo-e 1831, Edwardian newspaper,
etc., as the rubric's reference examples show). Skeletons in
templates/sample-pair/ for the four core scenarios.
Score with both scripts/dataset-scorer.py AND scripts/llm-judge.py.
Targets:
8-dim: AI scores โฅ 9/16, anti scores โค 4/16, mean delta โฅ +6
LLM 0-100: AI scores โฅ 60, anti scores โค 20, mean delta โฅ +50
If either scorer doesn't distinguish them, fix the rubric โ don't
loosen the threshold.
Export to LLM training format with scripts/export_dpo.py (or
the inline export in the 12-pair walkthrough in
references/llm-scoring-approach.md). Produces:
output/few_shot_examples.json โ alternative format for in-context prompting
output/llm_judge_prompt.txt โ template for LLM-as-judge eval pipelines
Validate end-to-end with a few-shot prompt (capstone test).
Use scripts/make_prompt.py <scenario> to generate a copy-paste
prompt, send it to the user's preferred LLM, score the output
with scripts/dataset-scorer.py. A passing pipeline produces
output scoring โค 4/16 on the 8-dim rubric without any DPO
training. The verified result (2026-06-15, MiniMax-M2.7 on
dashboard): 2/16 โ within the noise of the hand-curated 1/16.
See references/iterative-refinement-log.md for the full 5-step
execution trace.
Why this is the recommended path (user signal 2026-06-15): the user
explicitly rejected both the "5 data sources to mine" approach and the
"100-style Curio-clone library" approach as too big to validate. They
asked for the smallest viable artifact that produces a measurable signal.
The 4-pair dataset scored +9.2 mean delta on the first run, validating
the rubric immediately. The lesson: build the smallest thing that can
fail informatively, then expand. Single-HTML scoring is too small to
validate a rubric; 100-style libraries are too big to iterate on. Paired
datasets hit the sweet spot.
Known ceiling: feature-level scoring (literal "Inter" substring
match) only catches surface AI-taste. The "combo pattern" that makes
output feel AI-generated is invisible to a regex. The 12-pair LLM
validation showed +70/100 delta vs +10.7/16 for 8-dim โ a 6.5x
improvement. Going past +50 LLM delta hits diminishing returns unless
you add orthogonal scenarios (mobile UI, print editorial, government
forms). Adding more dashboard / landing pairs at that point trains
the scorer to recognize the same patterns twice.
Workflow: scoring a single HTML (smoke test)
Use scripts/scanner.py for a quick check on one page. It scores against
Rams' Ten Principles (6 of 10 implemented) and fetches Met Open Access
evidence. ~200 lines, Python 3.9+ stdlib only.
python3 scripts/scanner.py path/to/page.html
For scoring a whole dataset of pairs, use scripts/dataset-scorer.py โ
different purpose, different output shape (per-pair delta + summary
report). For holistic 0-100 evaluation, use scripts/llm-judge.py (with
or without an OpenRouter API key).
Workflow: export paired dataset to DPO training format
Once a 12+ pair dataset scores cleanly, the next step is preference
fine-tuning. The export format and use case are documented in
references/llm-scoring-approach.md under "DPO export format".
Quick command (pseudo โ implementation inlined in the reference):
License of generated DESIGN.md files: whatever the user's project uses;
the spec itself is Apache-2.0.
Production deployments (real-world references)
When the user asks "is anyone actually using DESIGN.md in production?" or wants to see a working reference, point them at:
Curio Design (https://designbycurio.com) โ A 500+ design system library using DESIGN.md as the primary format for every style (Bauhaus Weimar 1919, Memphis 1981, Apple Liquid Glass 2024, Stripe 2024, ...). Each style page exposes both a human-readable DESIGN.md and a Figma Tokens Studio JSON export. They run an MCP server at https://mcp.designbycurio.com/mcp exposing three tools (search_styles, get_style_spec, apply_style) so AI coding agents (Claude Code, Cursor, Codex) can browse, fetch, and apply styles mid-conversation. Verified 2026-06-15: the design schema they use has a slightly different frontmatter (name / origin / era) than the Google spec's (name / version / description / colors / typography / ...) โ both are valid YAML/Markdown but Google's CLI linter expects the Google shape, so don't run npx @google/design.md lint against Curio's exported files.
Designs by Curio's TERMS section 8.2 (verified 2026-06-15): "Certain Design Packages reference well-known design movements, historical periods, and named brands (for example, 'Memphis 1981', 'Stripe 2024', or 'Bauhaus Weimar') for educational and descriptive purposes." This is the legal framing that makes a Curio-clone library legally defensible: educational/descriptive use of brand identities and movements, not reproduction. Document this in your project's TERMS if you build a similar library.
Pitfall: spec drift across implementations
The DESIGN.md spec is "alpha" and two production deployments (Google's reference + Curio) have already diverged on frontmatter shape. If the user is authoring for a specific consumer (their own agents, Curio's MCP, Google's CLI), match that consumer's expected shape โ don't blindly follow the Google example here. Steps:
Ask the user where the DESIGN.md will be consumed (own agents? external MCP server? Figma Tokens Studio?)
Match the frontmatter shape of that consumer (check consumer's docs / sample files)
Note in the deliverable which schema version was used (Google alpha, Curio variant, custom)
References
references/curio-architecture-analysis.md โ Curio Design (designbycurio.com) architecture analysis: three-layer model (library/discovery/delivery), metadata taxonomy, pricing tiers, MCP server tools, legal framing (TERMS 8.2), comparison with this skill, and three implementation paths (constraint-only, small library hybrid, full clone). Verified live 2026-06-15. Read this when the user asks "how to build something like Curio" or "do we need a harness pipeline".\n- references/data-sources-for-design-systems.md โ Verified status of museum APIs, design archives, and font-usage databases (Met, Cooper Hewitt, MoMA, Awwwards, Fonts In Use, Internet Archive). Tier 1/2/3/4 with what's blocked, what's token-required, and a 30-second verification recipe.
references/dieter-rams-ten-principles.md โ Structured YAML form of Rams' Ten Principles, parsed by scripts/scanner.py. Each principle has rule: (verifiable claim) and machine_check: (function name). 6 of 10 implemented; the other 4 documented for human review.
references/ai-taste-8-dimensions.md โ The 8-dimension AI-taste scoring rubric used by scripts/dataset-scorer.py (font_cliche, purple_gradient, glassmorphism, uniform_radius, emoji_icons, placeholder_copy, heavy_shadow, element_density). Each dimension has a 0-2 scoring rule, what to detect, and a historical reference example. Use this as the schema when extending the contrastive dataset.
references/llm-scoring-approach.md โ Companion to the 8-dim rubric. Explains the two-scorer pattern (8-dim + LLM 0-100), why 8-dim saturates around +10 delta, the LLM judge's 6.5x signal improvement on the 12-pair dataset, the 5 specific bug fixes found while building the LLM scorer (font-family substring false-positives, density false-positives on data tables, marketing stem matching, re shadowing, unescaped regex parens), and the DPO export format. Read this before extending the 8-dim rubric.
references/iterative-refinement-log.md โ Verified 5-step execution trace of the 12-pair dataset build: bug fixes (3), 4โ8โ12 pair expansion, DPO export, LLM judge, capstone few-shot test. Documents the 4 user preference signals ("ๅ ๅ" over "ๅบ่ฏฅ", "concrete over speculative", "reject the clone, build the original", "validate before scaling") and the 3 main empirical findings (element_density is the LLM-fail dimension, 8-dim is a gate not a score, LLM self-reports are 100% accurate when verified). Read this if you're starting a new project from this skill.
scripts/scanner.py โ Python 3.9+ stdlib-only. Scores a single HTML file against Rams' principles, fetches CC0 evidence from Met Open Access, emits a Markdown report. ~200 lines, no pip install. Run: python3 scripts/scanner.py path/to/page.html.
scripts/dataset-scorer.py โ Python 3.9+ stdlib-only. Scores a paired contrastive dataset (dataset/samples/{scenario}/{ai,anti}/*.html) against the 8-dim rubric. Emits JSON + Markdown report with per-pair scores, per-dimension deltas, and a summary strength-of-discriminator verdict. Run: python3 scripts/dataset-scorer.py ./dataset.
scripts/llm-judge.py โ Python 3.9+ stdlib-only. Holistic 0-100 LLM-style scorer. With OPENROUTER_API_KEY set, calls claude-sonnet-4 in batched mode (8 pairs/request). Without a key, falls back to a deterministic 0-100 heuristic that still produces 6.5x better delta than 8-dim. Companion to dataset-scorer.py โ run on the same dataset and compare. Run: python3 scripts/llm-judge.py ./dataset.
scripts/export_dpo.py โ Python 3.9+ stdlib-only. Reads the paired dataset and emits output/dpo_dataset.jsonl (system + prompt + chosen + rejected per pair), output/few_shot_examples.json (in-context learning format), and output/llm_judge_prompt.txt (template for LLM-as-judge eval). Run: python3 scripts/export_dpo.py from the project root.
scripts/make_prompt.py โ Python 3.9+ stdlib-only. Builds a copy-paste-ready few-shot prompt for a given scenario. Combines 3 positive examples (different design languages from the dataset) + 1 negative example + the explicit "no widget pile-up" constraint. Usage: python3 scripts/make_prompt.py dashboard > /tmp/prompt.txt, then paste into any LLM. The capstone test of the pipeline.
templates/sample-pair/ โ Per-scenario HTML pair skeletons (dashboard, landing, article, product) for extending the contrastive dataset. Each pair has a ai/ and anti/ directory with annotated exemplars to clone. Add new scenarios (login, form, modal, nav, pricing, settings, email, slide) by following the same scenario-{ai,anti}.html naming pattern.
templates/starter.md โ Minimal DESIGN.md scaffold to copy and modify.
