# Zenwrite Design Chain > Build new UI or audit/align existing UI for the ZenWrite scholarly-writing app — its light-primary, dual-sphere design system (Newsreader serif + Manrope, brand-violet content sphere, sky/emerald/rose community sphere) plus React 19 + Tailwind v4 and general web/a11y/responsive best practice. Use whenever creating, editing, reviewing, or "bringing into alignment" any ZenWrite component, panel, screen, or page — even when the user only says "build a component," "make this match our style," "audit this page," "clean up the styling," "check design consistency," or "flush drift." Both an auditor and a builder for the ZenWrite design chain (Tokens → Primitives → Components → Built → Patterns). - Skill: `joshuashepherd/zenwrite-design-chain` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add joshuashepherd/zenwrite-design-chain` - Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/zenwrite-design-chain/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/joshuashepherd/zenwrite-design-chain --- # ZenWrite Design Chain — Auditor & Builder Build UI that looks like it was always part of ZenWrite, or pull existing UI back into alignment. ZenWrite is a **light-primary, distraction-free scholarly writing sanctuary**: the manuscript is the hero, chrome fades when typing, and the app is split into two color spheres. Everything you produce must honor the chain **Tokens → Primitives → Components → Built Components → Patterns** and hold to React 19 + Tailwind v4 + web best practice. ## First: load the design chain The chain is the contract. Load it before building or auditing: 1. **If the repo has `docs/design/`** (ZenWrite repo) — that is the **live source of truth**. Read `docs/design/README.md` and the layer files (`01-tokens.md` … `06-prompt-engineering.md`) for whatever you're touching. Also read `src/index.css` `@theme` for current tokens. 2. **Otherwise (or as a fast summary)** — read [`references/design-chain.md`](references/design-chain.md), a portable mirror of the same chain. Keep [`references/react-tailwind-best-practices.md`](references/react-tailwind-best-practices.md) in mind for engineering/a11y/perf, and [`references/audit-checklist.md`](references/audit-checklist.md) for review severity. Non-negotiables (from the philosophy): - **Light-primary.** No global `prefers-color-scheme` dark mode; `dark:` only under an explicit `.dark` ancestor. - **Two spheres, kept separate.** Content = brand-violet (Create/Edit/Organize). Community = sky/emerald/rose (Engage/Manage/Analyze). Don't cross primary accents. - **Tokens, never hex.** `bg-brand-violet`, not `bg-[#14006a]`. No dynamic color strings. - **Deliberate type.** `font-serif` (Newsreader) for literary titles/body; `font-manrope` for uppercase eyebrows/labels. - **Chrome fades.** In the editor, secondary chrome idle-fades at `duration-700`; never add persistent editor chrome. ## Pick the mode - **Build mode** — user wants a new component, panel, screen, tile, or page → [Build workflow](#build-workflow). - **Audit mode** — user wants a review, alignment pass, consistency/design check, or "flush drift" on existing UI → [Audit workflow](#audit-workflow). If the ask is ambiguous ("work on the newsletter UI"), state which mode you're taking and why, then proceed. --- ## Build workflow Reason **down the chain**, reusing what exists before creating anything new. 1. **Locate in the chain.** What layer is this? A pill/badge → primitive. A panel/wizard → component. A full view → built component. A cross-cutting shell/overlay behavior → pattern. 2. **Determine the sphere.** Content (violet) or community (sky/emerald/rose)? Resolve accent classes via `getViewAccent(view)` from `src/lib/viewAccents.ts` — headers, tabs, nav active states only; primary CTAs stay brand-violet. 3. **Reuse first.** Before writing markup, check for an existing primitive/pattern to compose: `StatusChip`, `VoiceFidelityChip`, `StateLayouts` (Loading/Empty/Error), the slide-in panel shell, the full-screen wizard shell, the home-tile pattern, the ⌘K palette. Grep `src/components/`. Extract a new primitive only when a 2nd/3rd consumer already exists — avoid premature abstraction. 4. **Compose with tokens.** Use the canonical patterns from `references/design-chain.md` (Layers 3–5) verbatim as your skeleton — panel titles `font-serif text-lg font-light italic text-brand-violet`, cards `rounded-2xl border-brand-violet/10`, page shell `max-w-7xl mx-auto px-6 py-8`, correct z-index and `animate-in` motion. Every interactive element gets `focus-visible:ring-2 focus-visible:ring-brand-violet focus-visible:outline-none` and an accessible name. 5. **Wire it up.** New screens/panels get state in `App.tsx` (view switch or overlay boolean), respect the idle-fade contract, and route by manuscript type where relevant (article/book/lesson/newsletter → Editor; podcast/video → MediaSurface). 6. **Engineer it well.** Typed props, no `any`, local UI state only, keyboard + SR accessible, ESC/backdrop close for overlays, static color maps (never `bg-${c}-500`), responsive across mobile / `md+` / wide. See `references/react-tailwind-best-practices.md`. 7. **Self-check + validate.** Run the [12-point checklist](references/audit-checklist.md) on your own output, then `pnpm build:check` (and `RUN_BUILD_VALIDATION=true pnpm build:check`). Fix TS errors in `reports/tsc.txt`. **Output:** the component/screen file(s) in `src/components/`, any `App.tsx` wiring, a note on which primitives/patterns you reused, and confirmation the build check passed (or the errors if not). --- ## Audit workflow Find drift, grade it, fix it — without inventing a new design. 1. **Scope.** Confirm target: specific files, a route/screen, or a full `src/` sweep ("flush drift"). 2. **Mechanical scan.** Run the scanner: ```bash bash /scripts/audit-scan.sh src # or narrow: ... src/components/EngageScreen.tsx ``` It surfaces hardcoded hex, dynamic color strings, missing focus rings, dark-mode hijacks, ad-hoc status badges, and font hygiene. It **locates**; you **judge** each hit. 3. **Chain review.** For each file, walk the [12-point reconstruction checklist](references/audit-checklist.md) and assign severity (CRITICAL / HIGH / MEDIUM / LOW). Check sphere discipline, typography layer, token usage, focus/a11y, z-index, StateLayouts/StatusChip reuse, and responsive behavior. 4. **Report.** List findings **most-severe first**, each as `file:line → what's wrong → concrete fix (exact token/class)`. Group by file. Note anything that's an intentional, documented exception rather than drift. 5. **Fix (when asked to align, not just report).** Apply lowest-risk fixes first (token swaps, focus rings, StatusChip/StateLayouts substitution) → then structural (primitive extraction, z-index, sphere correction). **Never introduce a new hex or new token to fix a hit** — reuse existing tokens; only add to `@theme` for a genuinely new semantic color (rare — flag it). 6. **Validate.** `pnpm build:check` (+ Vite bundle variant). Resolve `reports/tsc.txt` errors. Re-run the scanner to confirm the hits are gone. **Output:** a severity-ranked findings report; if fixing, the edits plus a before/after summary and passing build check. --- ## Guardrails - **Don't redesign.** This skill enforces *the existing* ZenWrite system; it does not invent new visual language. If the user wants a new direction, say so and get explicit agreement first. - **Don't cross spheres.** Violet is not a community accent; sky/emerald/rose are not content accents. - **Don't add hex or dynamic color strings**, global dark mode, persistent editor chrome, or debug panels — these are the documented anti-patterns. - **Prefer composition over new abstractions.** Reuse primitives; extract only on real repetition. - When the repo's `docs/design/` disagrees with `references/design-chain.md`, **the repo wins** — it's the live source of truth and this reference may lag.