diff --git a/README.md b/README.md index a615a80..7d42fcb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **A design skill for Claude Code, Cursor, and Codex that refuses to look AI-generated.** -[Live demo →](https://www.usehallmark.com)  ·  twenty themes  ·  four verbs  ·  press `T` to cycle. +[Live demo →](https://www.usehallmark.com)  ·  twenty themes  ·  five verbs  ·  press `T` to cycle. Made by Together AI. @@ -10,11 +10,11 @@ Made by Together AI. Hallmark, a design skill that refuses to look AI-generated

-Hallmark picks a macrostructure for the brief, dresses it in one of twenty themes, runs fifty-seven 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. +Hallmark picks a macrostructure for the brief, dresses it in one of twenty themes, runs fifty-eight 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. --- -## Four verbs +## Five verbs | Verb | What it does | | --- | --- | @@ -22,6 +22,7 @@ Hallmark picks a macrostructure for the brief, dresses it in one of twenty theme | `hallmark audit ` | Score existing code against the anti-patterns. Punch list, no edits. | | `hallmark redesign ` | Throw out the structure, keep copy + IA + brand, rebuild with a different fingerprint. | | `hallmark study ` | Extract the **DNA** from a design you admire: macrostructure, type-pairing, colour anchor. Refuses pixel-clones and paid templates. Optionally emits a portable `design.md` for handoff to other AI tools. | +| `hallmark variants ` | Three structurally distinct directions for one brief, rendered live. Flip through them in a picker over your own localhost, pick one, keep building. | --- @@ -72,9 +73,11 @@ Each page is self-contained HTML + CSS, stamped with its macrostructure in the C --- -## Custom NEW +## Custom -When a brief carries creative intent that no catalog theme fits, Hallmark switches to **Custom** and designs the page from scratch: a made-to-measure palette, type, and layout. Same 57 slop-test gates, no template underneath. +When a brief carries creative intent that no catalog theme fits, Hallmark switches to **Custom** and designs the page from scratch: a made-to-measure palette, type, and layout. Same 58 slop-test gates, no template underneath. + +In v1.2 the custom route runs a full art-direction ritual: it names and rejects the category's reflex aesthetics, writes a slate of seven grounded directions, and a deterministic **draw** (`scripts/seed.mjs`) picks which one gets built, sometimes dealing wildcards from a design-history atlas. A scene sentence sets the light, a colour posture (Restrained · Committed · Full palette · Drenched) sets how far the palette commits, and a five-block direction contract written into the artifact gets audited promise by promise before shipping. @@ -91,6 +94,35 @@ It stays a quiet branch; vanilla briefs never see it. The protocol lives in [`cu --- +## Variants NEW + +`hallmark variants ` runs the ceremony once, then builds **three complete directions**: different macrostructure, different theme (one dark, one mid, one light paper, forced), different nav, different footer. A tiny zero-dependency picker server (`skills/hallmark/scripts/variants/`) shows all three as live frames; in an existing app each direction is a temporary route your own dev server renders, with a small chip in the corner to flip and pick. Choose one and Hallmark promotes it, archives the others under `.hallmark/variants/`, and logs the whole run. Say `riff` for a fourth direction. No Node available? The picker degrades to a static compare page, and a chat reply ("pick 2") always works. + +--- + +## Open models NEW + +Hallmark v1.2 is written to hold up on open-weight models, not just Claude. The mechanically checkable gates now live in a zero-dependency checker the model runs instead of eyeballing: + +``` +node skills/hallmark/scripts/sloplint.mjs --genre +``` + +The skill carries a Critical floor that survives truncated reads, text-only fallbacks for every visual check (GLM has no vision; the skill knows), and a per-model quirks file ([`references/models.md`](skills/hallmark/references/models.md)) that loads only off-Claude. + +Run it inside Claude Code on an open model via an Anthropic-compatible endpoint: + +```bash +# GLM (Z.ai) # Kimi (Moonshot) +export ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +export ANTHROPIC_AUTH_TOKEN= # ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic +export ANTHROPIC_MODEL="glm-5.2[1m]" # ANTHROPIC_MODEL=kimi-k3 +``` + +The `[1m]` suffix on GLM is load-bearing; dropping it silently shrinks the context. Kimi Code CLI users: it discovers skills in `~/.claude/skills/` only, so install Hallmark there rather than as a plugin. + +--- + ## Install ``` @@ -100,7 +132,7 @@ npx skills add nutlope/hallmark Re-run any time to update. Or copy [`SKILL.md`](skills/hallmark/SKILL.md) + [`references/`](skills/hallmark/references/) into: - **Claude Code**: `~/.claude/skills/hallmark/` -- **Cursor**: `.cursor/rules/hallmark.mdc` (body of `SKILL.md`, no frontmatter) +- **Cursor**: `.cursor/rules/hallmark.mdc` (body of `SKILL.md`, no frontmatter; this channel ships no scripts, so `variants` picks by chat reply and the slop test runs fully model-judged) - **Codex**: `~/.codex/skills/hallmark/` (personal) or `.codex/skills/hallmark/` (project-scoped) The rule-set lives in [`SKILL.md`](skills/hallmark/SKILL.md) and [`references/`](skills/hallmark/references/). Worked examples in [`docs/recipes.md`](docs/recipes.md) and [`docs/study-examples.md`](docs/study-examples.md). diff --git a/ROADMAP.md b/ROADMAP.md index 231bbb9..4d39f67 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,39 +1,47 @@ # Roadmap -What's next. +What's next. (v1.2 shipped: the `variants` verb + picker, the custom art-direction ritual with the draw and the direction atlas, the sloplint mechanical checker, open-model hardening + the eval harness, and the big token diet.) --- ## Now -**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. +**Land the new themes.** Five candidates + two alternates are proposed with visuals in `site/_proposals/five-themes.html` (Plate, Grid, Bench, Maison, Field; Ledger, Arcade). Waiting on the pick; each chosen theme gets tokens, axes comments, a spec file, and two example builds. + +**Run the eval matrix on real endpoints.** `eval/` is built; run the 6-brief matrix against GLM (Together) and Kimi (OpenRouter), iterate the skill text until the acceptance criteria in `eval/README.md` hold, and publish the compare gallery. Re-run when Together lands Kimi K3. + +**Nanobanana hook for image-heavy briefs.** Recommend-only today. First-class hook: write the prompt, invoke the API, ingest the image, wire it into the build (cache by prompt hash). Pairs with the Plate theme candidate. --- ## Next -**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. +**sloplint as an edit-time hook.** The checker currently runs at Step 7. Wire it as a PostToolUse hook so mechanical slop is caught the moment a file is written, before the model moves on. -**Theme-aware motion tokens.** Per-theme `--dur-micro` / `--dur-short` / `--dur-long`, scaled by the table already in [`microinteractions.md`](skills/hallmark/references/microinteractions.md). Atelier should feel slower than Brutal; today they share durations. One pass through the tokens file. +**Theme spec files for the remaining 16 themes.** Only Carnival, Cobalt, Hum, and Lumen carry signature-move specs today. Cap each at ~150 lines; the tokens block cannot encode voice. -**`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. +**Tier A harness runs.** `eval/gen-cli.mjs`: drive the real Claude Code binary headless per model (Z.ai / Moonshot Anthropic-shaped endpoints) to test skill triggering and load-order discipline, not just instruction-following. -**Structural cookbook.** [`structure.md`](skills/hallmark/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. +**Brand-first flow.** From a short product description, generate a complete brand (palette, type, voice, imagery) locked into a `design.md`; then every page builds against it. -**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. +**Theme-aware motion tokens.** Per-theme `--dur-micro` / `--dur-short` / `--dur-long`; Atelier should feel slower than Brutal. -**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. +**Multi-page coherence.** Lock the brand axes, vary the page-voice axes: different pages of the same site, not different sites. -**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*. +**`study` reads your own codebase.** Third input mode: a path. Walk the files, extract the tokens + fingerprint in use, emit the same `design.md`. -**`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. +**Structural cookbook.** Twelve to twenty worked fingerprints with short HTML/CSS sketches; patterns are easier to reach for than principles. + +**Charts reference.** A `data-viz.md`: small multiples over dense singles, one accent + neutrals, the worst chart types banned outright. --- ## Later -- **`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. +- **Grow the direction atlas.** More lineages, usage-weighted dealing, a ratings pass so strong directions surface more often. +- **Per-harness prebuilt bundles.** Compiled copies for Gemini CLI, Copilot, OpenCode and friends, with placeholder substitution per harness. +- **`hallmark explain`** - narrate the choices axis by axis; the skill teaches. +- **Negative-capability rules** - for each anti-pattern, the perceptual reason it fails. +- **Emotion-first prompting** - *nostalgic · optimistic · sceptical* instead of tone adjectives. +- **Sound + haptic policy** - when web sound is acceptable without kitsch. +- **Live preview as an MCP server** - watch, render, screenshot, feed back into the gate sweep (the `--render` tier is the seed of this). diff --git a/package.json b/package.json index ded1f0d..642c7a6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hallmark", - "version": "1.1.0", + "version": "1.2.0", "description": "A design skill for AI coding assistants. Makes the UIs they generate look made, not generated. Powered by Together AI.", "keywords": [ "claude", @@ -13,7 +13,11 @@ "anti-ai-slop", "typography", "oklch", - "together-ai" + "together-ai", + "variants", + "open-models", + "glm", + "kimi" ], "license": "MIT", "type": "module",