The format at https://stitch.withgoogle.com/docs/design-md/format/ defines
exactly six sections in a fixed order: Overview, Colors, Typography,
Elevation, Components, Do's and Don'ts. Our previous format used
non-compliant names (Visual Theme & Atmosphere, Color Palette & Roles,
Typography Rules, Component Stylings), a non-existent "Layout Principles"
section, and had no Do's and Don'ts.
Changes to reference/document.md:
- Fixed section list to match the spec character-for-character
- Added mandatory "Creative North Star" pattern at top of Overview
- Added Named Rules pattern (e.g. "The No-Line Rule") — stickier than
bullet lists for AI consumers, mirrors Stitch's own generator output
- Added explicit Do's and Don'ts section with concrete, forceful guardrails
- Elevation is now its own section (was buried in Components)
- Layout/motion/responsive content folds into Overview + Components
rather than inventing new top-level sections
- Guidance on forceful voice ("prohibited"/"forbidden"/"never") matching
PRODUCT.md's expert-decisive tone
- Pitfalls section warns against renaming sections or adding new ones
Changes to our DESIGN.md:
- Rewrote to use spec-compliant section headers with evocative subtitles
(e.g. "## 2. Colors: The Warm-Paper Palette")
- Opened with "Creative North Star: The Editorial Sanctuary"
- Added 11 Named Rules across sections (The One Voice Rule, The Paper-
Not-White Rule, The OKLCH-Only Rule, The Italic-Is-Voice Rule,
The 1.6 Leading Rule, The Fluid-Headlines-Only Rule, The Flat-By-
Default Rule, The Low-Alpha Rule, The Tinted-Shadow-Only-For-Accent
Rule, plus the existing implicit ones)
- Full Do's and Don'ts section with 10 Dos and 15 Don'ts, many of which
translate PRODUCT.md anti-references into concrete prohibitions
- Elevation section documents shadow vocabulary separately from Components
- Layout/spacing/motion content relocated to a sub-section under Components
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pioneers a two-file convention for project context:
- PRODUCT.md (strategic): users, brand, principles — answers who/what/why
- DESIGN.md (visual): follows Google's Stitch DESIGN.md spec — answers how-it-looks
Both files live at the repo root. Filename matching is case-insensitive.
DESIGN.md wins on visual conflicts, PRODUCT.md wins on strategic/voice.
Legacy .impeccable.md is auto-migrated to PRODUCT.md on first read by the
new shared loader. This is silent and one-shot — the rename is permanent.
What changed:
- New scripts/load-context.mjs: shared context loader used by every command
that needs project context. Reads both files, handles legacy migration.
- New reference/document.md: /impeccable document command that generates
DESIGN.md by auto-extracting tokens (colors, typography, spacing, radii,
shadows, components) from CSS/Tailwind/theme files, then asking the user
to confirm descriptive language for atmosphere and color character.
Follows Google's Stitch DESIGN.md format for tool compatibility.
- SKILL.md Context Gathering Protocol updated to load both files and
nudge the user to run /impeccable document when DESIGN.md is missing.
- reference/teach.md rewritten to split discovery cleanly: strategic
questions go to PRODUCT.md, visual/design-system work is delegated to
/impeccable document (skipped on empty projects).
- reference/live.md consumes {product, design, productPath, designPath,
migrated} from the loader instead of a single context blob.
- scripts/live.mjs uses the shared loader instead of inline file reading.
- Command count updated 22 → 23 (new: document). Metadata, router table,
command menu, periodic table viz, and homepage data all updated.
- .gitignore adds PRODUCT.md + DESIGN.md (repo-local, not shared).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Previously only bolder/quieter/animate/colorize/typeset/layout had
variant diversity rules. Added the same level of guidance for distill,
polish, adapt, delight, and overdrive so every live action has a
clear "each variant must differ on THIS axis" rule.
Also noted that overdrive should skip its reference's "propose and ask"
step in live mode (it's non-interactive — the user picks from variants).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two failure modes observed:
1. Claude generates N near-identical variants (small shade/size tweaks)
instead of meaningfully different design directions
2. When a sub-command like /bolder is chosen in the picker, Claude skips
loading reference/bolder.md and generates generic variants
Fixes:
- "Load reference file" is now a MANDATORY Step 2a, separate and
non-negotiable, called out as a critical failure to skip
- Added Step 2b "Plan 3+ distinctly different directions" with 7
structural axes variants must differ on (hierarchy, layout topology,
typography system, color strategy, density, tone, decomposition)
- Added action-specific diversity rules (bolder = different dimensions,
animate = different motion vocabulary, colorize = different hues, etc.)
- Freeform prompt guidance: honor the prompt direction but explore
meaningfully different interpretations, not three near-copies
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Previously, starting live mode required ~5-6 sequential bash calls:
read .impeccable.md, start server, check config, read reference, inject
tag, verify. The new live.mjs does all of this in a single command
(~340ms cold, ~90ms when reusing a running server) and returns everything
the agent needs in one JSON blob.
Workflow is now:
1. node live.mjs # start + inject + load context (1 bash call)
2. navigate browser # optional MCP call
3. node live-poll.mjs # enter poll loop
Reference doc collapsed to a single "Start Live Mode" section with the
one-command path plus a first-time config creation fallback.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
First live run: agent auto-detects framework and writes a small config.json
(file, insertBefore/insertAfter anchor, comment syntax). Every subsequent
run: live-inject.mjs handles insert/remove deterministically, no LLM needed.
The config lives at {scripts_path}/config.json and is gitignored — it's a
per-project cache that wipes on skill update and regenerates on next use.
- New live-inject.mjs: --port (insert), --remove, --check modes
- Idempotent insert: re-running with a different port replaces cleanly
- Reference doc: one-time detection step, then instant insert/remove
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Arrow keys now pass through to element picker when the freeform input
is empty, instead of being swallowed by stopPropagation
- Arrow nav works in both PICKING and CONFIGURING states, so you can
change your element selection while the config bar is open
- Clicking outside the selected element and bar returns to PICKING mode,
matching the expected deselect behavior
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Accept and discard in live variant mode are now handled by a deterministic
script (live-accept.mjs) that runs inside the poller before returning to
the agent. The browser updates the DOM instantly on click (fire-and-forget)
so the user is never blocked waiting for LLM-driven file cleanup.
Key changes:
- New live-accept.mjs: deterministic accept/discard file operations
- Poller auto-runs accept script for accept/discard events (_acceptResult)
- Browser handleAccept() now commits DOM change instantly, no SAVING state
- CSS+HTML colocated in one write (style tag inside variant wrapper)
- SSE heartbeat every 30s prevents silent connection drops
- Poll timeout increased from 2min to 10min
- EventSource onopen resets retry counter for reliable reconnection
- Server --background flag for clean single-command startup
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Comprehensive architecture decision record covering the live variant
mode: context, key decisions (source modification over DOM patching,
SSE over WebSocket, self-contained skill scripts, HTTP long-poll for
agent), full architecture diagram with message flows, variant wrapper
format, browser UI states, session persistence, security model,
server resilience, performance optimizations, test coverage, known
limitations, and future work.
Also picks up improvements from parallel thread: poll timeout bumped
to 10 min, SSE heartbeat every 30s, and other minor fixes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
os.tmpdir() returns /var/folders/.../T/ on macOS, not /tmp/. The skill
reference was telling the agent to cat /tmp/impeccable-live.json which
didn't exist. Moving the PID file to the project root makes it
predictable across platforms and project-scoped (multiple projects can
run independent live sessions).
Changed in: live-server.mjs, live-poll.mjs, live.md reference.
Added .impeccable-live.json to .gitignore.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CI was running `bun test` which ran jsdom fixture tests in bun, causing
timeouts. Now uses `bun run test` which runs unit tests in bun and fixture
tests in node.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add first-class Pi (pi.dev) provider with transformer, tests, and build integration
- Fix CODEOWNERS username (@paulbakaus → @pbakaus)
- Add missing providers to issue/PR templates (Copilot, Kiro, OpenCode, Pi)
- Add Pi and OpenCode logos to homepage hero and install sections
- Move /onboard from "system" to "enhancement" category
- Update README and DEVELOP.md with all supported providers
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Run tests on push and PR to main
- Build project and upload artifacts
- Use Bun for fast JavaScript runtime
This ensures code quality and prevents regressions.
