From c2f20b0cb80924e1a64bb6473d85b8c561191ae5 Mon Sep 17 00:00:00 2001 From: Arda <233561772+ardamoustafa1@users.noreply.github.com> Date: Fri, 17 Jul 2026 16:13:19 +0300 Subject: [PATCH] Elevate DesignOS quality system and onboarding --- AGENTS.md | 16 +- CHEATSHEET.md | 2 +- CLAUDE.md | 16 +- GETTING-STARTED.md | 9 +- README.md | 673 ++++++++++++++++++++++---------- bin/designos.js | 76 ++-- brain/brief-compiler.md | 102 +++++ brain/trend-radar.md | 3 + checklists/accessibility.md | 18 +- foundations/accessibility.md | 14 +- loops/design-loop.md | 44 ++- prompts/prompt-cookbook.md | 34 +- recipes/admin-dashboard.md | 4 +- recipes/investor-demo-page.md | 4 +- recipes/mobile-onboarding.md | 4 +- recipes/saas-pricing-page.md | 4 +- recipes/stripe-level-landing.md | 4 +- scoring/report-template.md | 7 + scoring/rubric.md | 13 +- skills/README.md | 2 +- skills/design-brief.md | 10 +- validators/test-cli.js | 16 + workflows/final-gate.md | 27 +- 23 files changed, 800 insertions(+), 302 deletions(-) create mode 100644 brain/brief-compiler.md diff --git a/AGENTS.md b/AGENTS.md index e84f7598..4a0c4581 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,13 +27,14 @@ This file is the kernel. It tells you **what to load, in what order, and what st ``` 1. READ brain/design-intelligence.md → how to think 2. READ brain/decision-framework.md → how to choose -3. ROUTE via the table below → load only relevant modules -4. LOAD industries/.md → sector conventions, if known -5. LOAD memory/ project files → client, brand, prior decisions -6. RUN loops/design-loop.md → produce the work -7. SCORE scoring/rubric.md → self-review, iterate under 95 -8. GATE workflows/final-gate.md → run deterministic review if files exist -9. WRITE memory/ updates → record decisions and open items +3. COMPILE brain/brief-compiler.md → turn the request into a testable contract +4. ROUTE via the table below → load only relevant modules +5. LOAD industries/.md → sector conventions, if known +6. LOAD memory/ project files → client, brand, prior decisions +7. RUN loops/design-loop.md → produce the work +8. SCORE scoring/rubric.md → self-review, iterate under 95 +9. GATE workflows/final-gate.md → run deterministic review if files exist +10. WRITE memory/ updates → record decisions and open items ``` Do not skip steps. If a module doesn't exist for the task, say so — do not improvise silently. @@ -44,6 +45,7 @@ Do not skip steps. If a module doesn't exist for the task, say so — do not imp | Task signal | Load | |---|---| +| Vague brief, prompt writing, "premium/beautiful/modern" without specifics | `brain/brief-compiler.md`, `brain/originality.md`, `PROOF_STANDARD.md` | | Landing page, marketing site | `patterns/landing-pages.md`, `components/hero.md`, `psychology/` (attention, persuasion, trust), `components/footer.md` | | Hero section | `components/hero.md`, `psychology/attention.md`, `foundations/typography.md` | | Glow, gradients, grain, glass, "wow" effects | `components/visual-effects.md`, `brain/originality.md`, `motion/performance.md` | diff --git a/CHEATSHEET.md b/CHEATSHEET.md index 9c6d0370..4b533161 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -15,7 +15,7 @@ MOTION 100/150/200/300/500ms · ease-out default · exits < entrances interactive ≤300ms · stagger ≤60ms × ≤6 · transform/opacity ONLY TARGETS 44×44px touch · 48px inputs · 40–48px buttons · 44–48px table rows PERF LCP <2.0s · CLS <0.1 · INP <200ms · Lighthouse ≥95 · page ≤1.5MB -SCORE 6 dimensions · threshold 95 · AA failure caps at 60 · max 3 loop cycles +SCORE 7 dimensions · threshold 95 · AA failure caps at 60 · max 3 loop cycles ``` ## The one-of-each laws diff --git a/CLAUDE.md b/CLAUDE.md index e84f7598..4a0c4581 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,13 +27,14 @@ This file is the kernel. It tells you **what to load, in what order, and what st ``` 1. READ brain/design-intelligence.md → how to think 2. READ brain/decision-framework.md → how to choose -3. ROUTE via the table below → load only relevant modules -4. LOAD industries/.md → sector conventions, if known -5. LOAD memory/ project files → client, brand, prior decisions -6. RUN loops/design-loop.md → produce the work -7. SCORE scoring/rubric.md → self-review, iterate under 95 -8. GATE workflows/final-gate.md → run deterministic review if files exist -9. WRITE memory/ updates → record decisions and open items +3. COMPILE brain/brief-compiler.md → turn the request into a testable contract +4. ROUTE via the table below → load only relevant modules +5. LOAD industries/.md → sector conventions, if known +6. LOAD memory/ project files → client, brand, prior decisions +7. RUN loops/design-loop.md → produce the work +8. SCORE scoring/rubric.md → self-review, iterate under 95 +9. GATE workflows/final-gate.md → run deterministic review if files exist +10. WRITE memory/ updates → record decisions and open items ``` Do not skip steps. If a module doesn't exist for the task, say so — do not improvise silently. @@ -44,6 +45,7 @@ Do not skip steps. If a module doesn't exist for the task, say so — do not imp | Task signal | Load | |---|---| +| Vague brief, prompt writing, "premium/beautiful/modern" without specifics | `brain/brief-compiler.md`, `brain/originality.md`, `PROOF_STANDARD.md` | | Landing page, marketing site | `patterns/landing-pages.md`, `components/hero.md`, `psychology/` (attention, persuasion, trust), `components/footer.md` | | Hero section | `components/hero.md`, `psychology/attention.md`, `foundations/typography.md` | | Glow, gradients, grain, glass, "wow" effects | `components/visual-effects.md`, `brain/originality.md`, `motion/performance.md` | diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index 42ce80e9..5e91aa75 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -27,8 +27,9 @@ node DesignOS/bin/designos.js elevate src/ --no-fail node DesignOS/bin/designos.js report src/ --no-fail ``` -Treat the agent's own score as a draft. The real score is the output from -`node DesignOS/bin/designos.js review `. If the command reports findings, paste +Treat the agent's own score as a draft. `node DesignOS/bin/designos.js review ` +is a static risk gate, not the final design score; complete the evidence ledger in +`workflows/final-gate.md` before making a numeric claim. If the command reports findings, paste `node DesignOS/bin/designos.js review --fix-prompt --no-fail` back into the agent and make it fix the file before accepting the delivery. @@ -78,8 +79,8 @@ directly observable, not a black box: `patterns/landing-pages.md`, …) — see `CLAUDE.md`'s routing table for how that decision gets made. 2. It works through the Design Loop stages (`loops/design-loop.md`), not straight to code. -3. It ends with a scorecard (`scoring/rubric.md`) — and if any dimension is under 95, - it iterates *before* showing you, not after. +3. It ends with an evidence-backed scorecard (`scoring/rubric.md`) — unchecked dimensions + remain NOT ASSESSED, and reviewed failures route back into the loop. 4. It creates `memory/` files recording the decisions it made, with reasons. Don't want to write a real brief yet? `examples/README.md` has four complete pages diff --git a/README.md b/README.md index d4ec73af..e5aaf16a 100644 --- a/README.md +++ b/README.md @@ -32,304 +32,545 @@ --- -## Why this exists +## Start here -AI agents ship flawless logic wrapped in 2015-grade interfaces: cramped spacing, five -competing CTAs, gray-on-gray contrast failures, fake testimonials invented on the spot. -The model isn't missing capability — it's missing **taste, process, and a quality gate**. +DesignOS is a repository-native design intelligence layer for AI coding agents. It adds +the part a code model usually lacks: a repeatable way to understand the brief, derive a +distinct visual direction, select relevant design knowledge, inspect the rendered result, +and remember decisions across sessions. -DesignOS is all three, as an operating system the agent boots into: +It is not a component library and it does not replace your framework. It sits beside your +codebase as Markdown instructions, specialist roles, workflows, validators, and a small +zero-dependency CLI. -``` -You type: "Design a Stripe-level SaaS landing page." +> **The short version:** install once, verify the connection, then describe the interface +> you want. DesignOS routes the task through the right modules and leaves an inspectable +> trail of decisions, findings, and project memory. -DesignOS: boots the kernel → routes to the right modules → loads sector rules - → runs the Design Loop → scores itself across 6 dimensions - → REDOES anything under 95 → writes every decision to memory -``` +### What changes after installation? -The agent stops thinking *"I'll make a button"* and starts thinking -*"where does attention land, is the CTA winning, would Apple cut this element entirely?"* +| Without a design operating system | With DesignOS | +|---|---| +| The agent jumps from request to JSX | The brief becomes a testable design contract first | +| “Premium” becomes gradients and cards | Visual direction is derived from product material and brand belief | +| Every session starts from zero | Seven memory files preserve brand and system decisions | +| The author grades its own work informally | Specialist review, static checks, and an evidence ledger separate creation from verification | +| Happy-path mockups look finished | Loading, empty, error, success, keyboard, responsive, and reduced-motion states are considered | +| References become style imitation | DesignOS transfers tactics while prohibiting branded motifs | -## What makes it different +
+Table of contents + +- [Quick Start](#-quick-start) +- [Choose your agent](#choose-your-agent) +- [Create your first interface](#create-your-first-interface) +- [How It Works](#-how-it-works) +- [System architecture](#system-architecture) +- [Project memory](#project-memory) +- [CLI reference](#cli-reference) +- [Quality and evidence](#quality-and-evidence) +- [Examples and starters](#examples-and-starters) +- [Troubleshooting](#troubleshooting) +- [Community](#community) -| | Prompt packs | Component libraries | **DesignOS** | -|---|---|---|---| -| Encodes | wording tricks | pre-built UI | **judgment + process** | -| Quality control | none | none | adversarial self-scoring, hard 95 gate | -| Consistency across sessions | no | partial | 7-file project memory | -| Sector awareness | no | no | 24 industry playbooks | -| Honesty enforcement | no | no | fake proof & dark patterns = instant fail | -| Works with | one prompt | one framework | any agent, any stack — it's markdown | -| Measurable | no | no | [validators + blind eval protocol](evals/README.md) | - -**We're trying to measure this, not just claim it.** Below is a maintainer-run sanity -check — **not independent validation** ([full caveats](evals/RESULTS.md)) — showing the -validators catch what they're supposed to catch. The eval slot that would actually prove -the claim is open and unfilled; [run it and PR your numbers](evals/RESULTS.md#run-003--your-model-your-judge-the-one-that-matters-most). - -| Mechanical check (same brief) | Default-style output | Through DesignOS | -|---|---:|---:| -| Token-drift findings | 43 | **0** | -| A11y-basics findings | 6 | **0** | -| Body-text contrast | 2.85:1 ✗ | 6.28:1 ✓ | +
--- ## ⚡ Quick Start -One command, from your project directory: +### 1. Open your project directory + +Run the installer from the root of the project you want DesignOS to guide — not from +inside a DesignOS clone. ```bash +cd path/to/your-project npx github:ardamoustafa1/DesignOS init --agents --skills ``` -That copies the system into `./DesignOS`, wires `@DesignOS/CLAUDE.md` into your project's -`CLAUDE.md`, registers **9 specialist subagents** (creative director, a11y auditor, -adversarial reviewer…), and installs the slash commands: -`/design-review` · `/design-score` · `/design-brief` · `/design-tokens`. +The installer creates a local `./DesignOS` copy, connects the Claude kernel, and optionally +installs the nine specialist agents and four `/design-*` commands. + +```text +your-project/ +├── DesignOS/ design knowledge, workflows, CLI, validators +├── CLAUDE.md imports @DesignOS/CLAUDE.md +├── .claude/ +│ ├── agents/ 9 specialist roles +│ └── commands/ /design-brief · /design-review · /design-score · /design-tokens +└── your existing app files untouched by installation +``` + +### 2. Verify the connection -**Not on Claude Code?** One export, every agent ([capability matrix](integrations/README.md)). -`init` also copies the CLI itself to `DesignOS/bin/` — use that local path for every -command after install (⚠️ **not** bare `npx designos …` — that name is already taken by -an unrelated package on the npm registry): +All commands after installation use the local CLI copy: ```bash -node DesignOS/bin/designos.js export all # .cursorrules · copilot-instructions · .windsurfrules · .clinerules · CONVENTIONS.md · AGENTS.md -node DesignOS/bin/designos.js doctor # verify the install's health anytime -node DesignOS/bin/designos.js audit src/ # run all validators against your code -node DesignOS/bin/designos.js review src/ # score deterministic design risks +node DesignOS/bin/designos.js doctor +``` + +A healthy setup confirms the kernel, local CLI, import, agents, skills, and project-memory +status. If your agent is not Claude Code, export its native rules file next. + +> [!WARNING] +> Never run bare `npx designos ...`. That npm name belongs to an unrelated package. +> Use the GitHub installer once, then always use `node DesignOS/bin/designos.js ...`. + +### 3. Give it a real brief + +```text +Design a pricing page for a cybersecurity SaaS. + +Audience: security leaders comparing vendors before a technical evaluation. +Primary action: book a technical demo. +Product material: risk timeline, asset table, and investigation workflow. +Proof available: real dashboard screenshots; no customer logos yet. +Tone: calm, precise, high-trust. Dark theme, but no neon cyber clichés. +Stack: use the existing project stack and tokens. +``` + +A strong brief gives DesignOS material to derive from. If details are missing, the +[Brief Compiler](brain/brief-compiler.md) asks only high-impact questions or records +explicit assumptions instead of silently inventing facts. + +### 4. Review the result + +```bash +node DesignOS/bin/designos.js audit src/ node DesignOS/bin/designos.js review src/ --fix-prompt --no-fail -node DesignOS/bin/designos.js visual index.html --no-fail # screenshots if Playwright is installed -node DesignOS/bin/designos.js report src/ --no-fail # delivery report + fix prompt + sign-off checklist -node DesignOS/bin/designos.js elevate src/ --no-fail # premium refactor prompt for taste/signature -node DesignOS/bin/designos.js starter landing-page my-launch -node DesignOS/bin/designos.js brief --interactive -node DesignOS/bin/designos.js brief --type pricing --industry fintech --audience CFOs --goal "book demos" -node DesignOS/bin/designos.js eval cursor-pricing --agent Cursor --brief B-001 -node DesignOS/bin/designos.js case acme-pricing --project "Acme Pricing" --url https://example.com +node DesignOS/bin/designos.js visual path/to/page.html --no-fail +node DesignOS/bin/designos.js report src/ --no-fail ``` -**Important:** agent self-scores are not accepted as final. A page is only "95+" or -"100/100" when `designos review ` says so. If the review fails, run -`designos review --fix-prompt --no-fail`, paste the prompt back into your agent, -and iterate until the deterministic gate is clean. +`review` reports static source risks. It is intentionally not presented as proof of +visual quality, WCAG conformance, performance, or conversion. Final claims require the +[evidence ledger](workflows/final-gate.md). + +--- + +## Choose your agent + +The knowledge system is shared; the connection step differs by tool. + +| Agent | After `init` | What it creates | Capability | +|---|---|---|---| +| Claude Code | Nothing else required | `CLAUDE.md`, specialist agents, slash commands | Full kernel + native subagents/commands | +| Codex, Gemini CLI, Amp, Zed, Jules | `export agentsmd` | `AGENTS.md` | Kernel through the agents.md convention | +| Cursor | `export cursor` | `.cursorrules` | Kernel rules in project context | +| GitHub Copilot | `export copilot` | `.github/copilot-instructions.md` | Repository instructions | +| Windsurf | `export windsurf` | `.windsurfrules` | Workspace rules | +| Cline | `export cline` | `.clinerules` | Project rules | +| Aider | `export aider` | `CONVENTIONS.md` | Repository conventions | + +```bash +# Choose one, or generate every supported rules file: +node DesignOS/bin/designos.js export agentsmd +node DesignOS/bin/designos.js export cursor +node DesignOS/bin/designos.js export copilot +node DesignOS/bin/designos.js export windsurf +node DesignOS/bin/designos.js export cline +node DesignOS/bin/designos.js export aider +node DesignOS/bin/designos.js export all +``` -Agents that speak the open [agents.md standard](https://agents.md) (Codex CLI, Gemini CLI, -Amp, Zed, Jules…) need even less: this repo ships a root `AGENTS.md` kernel mirror they -pick up automatically, and `export agentsmd` writes one into your own project. +Existing non-DesignOS rules files are protected by default. The exporter warns instead of +overwriting them; review [the integration guide](integrations/README.md) before using +`--force`.
-Manual install (no npx) +Manual installation ```bash git clone https://github.com/ardamoustafa1/DesignOS.git -cd your-project -cp -r ../DesignOS ./DesignOS -echo "@DesignOS/CLAUDE.md" >> CLAUDE.md # Claude Code auto-loads it -cp DesignOS/agents/*.md .claude/agents/ # optional: real subagents -cp DesignOS/skills/design-*.md .claude/commands/ # optional: slash commands - -# or globally, for all projects: -cp -r ../DesignOS ~/.claude/DesignOS +cd path/to/your-project +cp -r path/to/DesignOS ./DesignOS +echo "@DesignOS/CLAUDE.md" >> CLAUDE.md + +# Optional Claude Code integrations +cp DesignOS/agents/*.md .claude/agents/ +cp DesignOS/skills/design-*.md .claude/commands/ ``` + +Run `node DesignOS/bin/designos.js doctor` afterwards. For non-Claude agents, use the +appropriate export command rather than hand-copying the kernel. +
-Then just ask: +
+Global installation -> *Design a pricing page for a cybersecurity SaaS. Dark theme.* +```bash +cp -r path/to/DesignOS ~/.claude/DesignOS +echo "@~/.claude/DesignOS/CLAUDE.md" >> ~/.claude/CLAUDE.md +``` -Watch it route `industries/cybersecurity.md` + `patterns/pricing.md` + -`psychology/persuasion.md`, run the loop, and refuse to hand you anything under 95. +Local project installation is recommended when teams need versioned, reproducible rules. -Full walkthrough (verification steps, memory model, steering commands, troubleshooting): -**[GETTING-STARTED.md](GETTING-STARTED.md)**. +
--- -## 🔍 How It Works +## Create your first interface + +There are three good entry points. Pick the one that matches how much you already know. -DesignOS isn't a black box — every stage is observable in the agent's own output. -One brief moves through a fixed control flow ([full diagram + module anatomy → -ARCHITECTURE.md](ARCHITECTURE.md)): +### A. Ask naturally +```text +Build a premium landing page for an AI incident-response product. +Use our existing stack. The hero must show the real investigation timeline. +Primary action is starting a sandbox. Do not invent logos, metrics, or compliance claims. +Run the full DesignOS loop and show what was not verified. ``` -your brief - │ - ▼ -KERNEL BOOTS (CLAUDE.md) ──▶ ROUTES by task + sector ──▶ LOADS only the relevant - │ (routing table) modules + project memory - ▼ -DESIGN LOOP research → wireframe → ui → review → a11y → perf → seo → refactor - │ - ▼ -REVIEW ENGINE scores 6 dimensions against a written rubric - │ - ├── any dimension < 95 ──▶ specific objections feed back into the loop (max 3 cycles) - │ - ▼ all ≥ 95 -DELIVERED: artifact + scorecard + rationale + memory written for next time + +### B. Generate a structured brief + +```bash +node DesignOS/bin/designos.js brief --interactive ``` -That loop is not a diagram we're asking you to trust — it's the exact process in -[`examples/saas-landing-walkthrough.md`](examples/saas-landing-walkthrough.md), including -two real failures the loop caught and fixed before delivery. Want to watch it run on a -brief you pick? [GETTING-STARTED.md](GETTING-STARTED.md) step 3 tells you what to look for. +Or create one non-interactively: + +```bash +node DesignOS/bin/designos.js brief \ + --type pricing \ + --industry fintech \ + --audience "finance operations leaders" \ + --goal "start a guided trial" \ + --tone "precise, calm, evidence-first" \ + --constraints "existing React stack, light theme, WCAG 2.2 AA target" +``` + +### C. Use a ready-made recipe + +Start from [recipes](recipes/README.md) for common surfaces: + +- [Stripe-level landing page](recipes/stripe-level-landing.md) +- [SaaS pricing page](recipes/saas-pricing-page.md) +- [Admin dashboard](recipes/admin-dashboard.md) +- [Mobile onboarding](recipes/mobile-onboarding.md) +- [Investor demo page](recipes/investor-demo-page.md) + +Each recipe is a high-signal brief, not an alternate mini-kernel. It still boots the same +DesignOS process, originality discipline, render inspection, and evidence rules. --- -## The Five Layers +## 🔍 How It Works + +DesignOS makes the design process observable. One request moves through a fixed control +flow; findings return to the stage that caused them. + +```mermaid +flowchart TB + A["Your brief"] --> B["Kernel boots"] + B --> C["Brief Compiler
intent · audience · truth · constraints"] + C --> D["Router
task × sector × surface"] + D --> E["Relevant modules + project memory"] + E --> F["Research + 3 design directions"] + F --> G["Wireframe + UI implementation"] + G --> H["Render and inspect
375 · 768 · 1024 · 1440"] + H --> I["Specialist review
creative · a11y · engineering"] + I --> J{"Evidence-backed gate"} + J -- "finding" --> K["Route to responsible stage"] + K --> F + J -- "verified" --> L["Artifact + rationale + memory updates"] +``` -| Layer | What it does | Where | +### The loop, stage by stage + +| Stage | Question answered | Concrete output | |---|---|---| -| **1 · Knowledge** | 60+ opinionated modules — every rule with its reason | [`foundations/`](foundations/) [`components/`](components/) [`psychology/`](psychology/) [`motion/`](motion/) [`patterns/`](patterns/) [`native/`](native/) | -| **2 · Loops** | Research → Wireframe → UI → Review → A11y → Perf → SEO → Refactor → Score — no stage skipped | [`loops/`](loops/) | -| **3 · Review Engine** | Adversarial self-scoring: 6 dimensions, hard 95 threshold, a11y failures cap at 60 | [`scoring/`](scoring/) + [`validators/`](validators/) | -| **4 · Memory** | 7 files per project — decision #40 stays consistent with decision #4 | [`memory/`](memory/) | -| **5 · Industry Intelligence** | 24 sector playbooks: what fintech trusts, what gaming licenses, what healthcare forbids | [`industries/`](industries/) | +| Contract | What must this cause, for whom, using what truth? | Intent, audience state, proof/assets, never-list, acceptance evidence | +| Directions | What could make this product unmistakable? | Material-led, audience-led, and belief-led hypotheses | +| Wireframe | In what order should attention move? | Section structure, eye path, primary action, responsive priorities | +| UI | What system expresses that hierarchy? | Tokens, type, spacing, components, states, motion | +| Render/Inspect | Does the real artifact match the source-code intention? | Viewport evidence, visual findings, corrected implementation | +| Specialist review | Is it coherent, usable, accessible, fast, and truthful? | Findings with owner and severity | +| Final Gate | What was actually checked? | Static risk output + evidence ledger + NOT ASSESSED disclosures | +| Memory | What must the next session remember? | Durable decisions, status, bugs, and open work | + +Read the complete contracts in [the Design Loop](loops/design-loop.md) and the +[Final Gate](workflows/final-gate.md). -
-📁 Full repository map +--- +## System architecture + +DesignOS uses a small kernel and lazy-loads detailed modules only when they change a +decision. This keeps the agent focused instead of flooding its context with every rule. + +```mermaid +flowchart LR + K["Kernel
CLAUDE.md · AGENTS.md"] --> R["Router"] + R --> B["Brain
intent · decisions · originality"] + R --> N["Knowledge
foundations · components · patterns"] + R --> S["Sector intelligence
24 industry playbooks"] + B --> P["Process
loops · workflows · agents"] + N --> P + S --> P + M["Project memory
7 durable files"] <--> P + P --> Q["Quality
rubric · checklists · validators"] + Q --> O["Artifact + evidence + rationale"] ``` + +### The seven layers + +| Layer | Responsibility | Explore | +|---|---|---| +| Kernel | Boot order, routing table, non-negotiable standards | [CLAUDE.md](CLAUDE.md) · [AGENTS.md](AGENTS.md) | +| Design brain | Intent, decision rules, taste, originality, reference transfer | [brain](brain/) | +| Knowledge | Foundations, components, patterns, motion, psychology, native UI | [foundations](foundations/) · [components](components/) · [patterns](patterns/) | +| Sector intelligence | Buyer psychology, trust requirements, visual licenses | [industries](industries/) | +| Process | Design/review loops, workflows, and specialist roles | [loops](loops/) · [workflows](workflows/) · [agents](agents/) | +| Memory | Brand, system, pages, tasks, bugs, notes | [memory](memory/) | +| Evidence | Rubric, checklists, static validators, eval protocol | [scoring](scoring/) · [checklists](checklists/) · [validators](validators/) · [evals](evals/) | + +
+Repository map + +```text DesignOS/ -├── CLAUDE.md ← the kernel: boot sequence, routing table, standards, output contract -├── AGENTS.md ← byte-identical kernel mirror for agents.md-standard tools (CI-enforced sync) -├── llms.txt ← llmstxt.org discovery map for LLM consumers -├── brain/ ← how to think: intelligence · decisions · quality bar · taste ladder · -│ references · trend radar · originality -├── references/ ← visual taste packs: Stripe-level · Linear-style · Apple · Vercel docs · cyber dark -├── goldens/ ← target bars for premium pricing, dashboards, docs, onboarding, AI landing -├── agents/ ← 9 specialist personas (Claude Code subagent-compatible) -├── foundations/ ← colors · typography · spacing · layout · grids · icons · a11y · -│ design tokens · dark mode · RTL & i18n -├── components/ ← buttons · forms · cards · nav · footer · hero · visual effects · dashboard · data density · -│ tables · modals · states · skeletons · badges · tooltips · tabs · -│ search & ⌘K · notifications · charts · code blocks · wizards · upload · pickers -├── psychology/ ← attention · persuasion · cognition · color · trust · emotion · -│ gamification · habit & retention -├── motion/ ← principles · micro-interactions · page & scroll · performance -├── patterns/ ← landing · pricing · onboarding · product tours · docs · blog · changelog · -│ settings · comparison · company pages · email · print · AI/chat UI -├── native/ ← iOS · Android · app patterns · motion & gestures -├── industries/ ← 24 sector playbooks (SaaS → AI → Fintech → … → Manufacturing) -├── loops/ workflows/ ← the processes: design/review/refactor loops, production workflows -├── scoring/ checklists/ ← rubric · scorecards · failure taxonomy · 5 quality gates -├── validators/ ← zero-dep CI scripts: refs · token drift · contrast · a11y basics -├── evals/ ← blind benchmark protocol + independent-run guide + published RESULTS -├── memory/ ← per-project memory protocol + 7 templates + design personality packs -├── skills/ ← the /design-* slash commands -├── integrations/ ← one export, every agent -├── museum/ ← the Anti-Pattern Museum: 40+ cataloged design crimes -├── starter/ ← tokens + copyable starter code for landing, docs, Next, React, mobile -├── recipes/ ← copy-ready high-demand UI prompts -├── adapters/ ← best-practice setup per agent surface -├── playbooks/ ← real-project adoption plans -├── actions/ ← DesignOS Review Action docs -├── examples/ ← 4-page live showcase, each with its decision walkthrough -├── website/ ← the project's own site — designed by the system itself -├── press/ ← logos, boilerplate, the demo SVG -└── bin/ ← the CLI: init · review · visual · report · elevate · starter · eval · case · doctor +├── CLAUDE.md · AGENTS.md kernel and routing +├── brain/ design reasoning and originality +├── foundations/ color, type, spacing, layout, tokens, a11y +├── components/ UI component intelligence +├── patterns/ page and flow patterns +├── psychology/ attention, persuasion, trust, cognition +├── motion/ · native/ motion and platform-native guidance +├── industries/ 24 sector playbooks +├── agents/ 9 specialist roles +├── loops/ · workflows/ production and review processes +├── scoring/ · checklists/ review rubric and evidence requirements +├── validators/ zero-dependency static checks +├── memory/ protocol, templates, personality packs +├── references/ · goldens/ reference tactics and target bars +├── starter/ · recipes/ executable starting points +├── examples/ · website/ inspectable demonstrations +├── evals/ · case-studies/ measurement and field evidence +└── bin/designos.js installer and local CLI ``` +
-Plus a **nine-agent studio** ([`agents/`](agents/)): creative director, UX researcher, -UI designer, frontend engineer, motion designer, accessibility specialist, copywriter, -SEO — and an adversarial reviewer with veto power. +--- -Quick references: [**CHEATSHEET**](CHEATSHEET.md) — the whole system on one page · -[**GLOSSARY**](GLOSSARY.md) — the vocabulary A–Z · -[**Proof Standard**](PROOF_STANDARD.md) — what claims are allowed to say · -[**Visual references**](references/README.md) — taste packs without copying · -[**Goldens**](goldens/README.md) — target bars + live HTML seeds for premium outputs · -[**The Anti-Pattern Museum**](museum/README.md) — 40+ design crimes, each with the rule that prevents it · -[**Field Report 001**](evals/field-report-001.md) — a real stress-test, a real gap found and fixed. +## Project memory + +Without memory, every new chat can quietly change the brand, spacing scale, terminology, +or page goals. DesignOS persists the reasoning, not only the final values. + +```mermaid +flowchart TD + C["client.md
audience · goals · constraints"] --> D["design work"] + B["brand.md
voice · type · color · never-list"] --> D + S["design.md
tokens · layout · motion · overrides"] --> D + D --> P["pages.md
inventory · intent · status"] + D --> T["todo.md
prioritized open work"] + D --> G["bugs.md
known defects"] + D --> N["notes.md
assumptions · feedback · review history"] + P --> NEXT["next session"] + T --> NEXT + G --> NEXT + N --> NEXT +``` -Adoption surfaces: [**Real project playbook**](playbooks/real-project-adoption.md) · -[**Team rollout**](playbooks/team-rollout.md) · [**PR review workflow**](playbooks/pr-review-workflow.md) · -[**Agent adapters**](adapters/README.md) · [**Starters**](starter/README.md) · -[**Recipes**](recipes/README.md) · [**Case studies**](case-studies/README.md). +Bootstrap the seven files from [memory/templates](memory/templates/) and follow the +[memory protocol](memory/README.md): decisions carry reasons, dates are absolute, +overrides are explicit, and superseded reasoning is preserved instead of erased. --- -## See it, don't take our word +## CLI reference + +Every command runs from your project root after installation. -🎭 **[The Before/After demo](website/before-after.html)** — the same brief with and -without DesignOS; every flaw on the "before" page pinned with its Museum exhibit number. +| Command | Purpose | Writes files? | +|---|---|---:| +| `doctor` | Verify kernel, CLI, integrations, skills, and memory | No | +| `export ` | Generate the selected agent's rules file | Yes | +| `brief` | Produce a structured, agent-ready design brief | Optional | +| `starter ` | Copy a production-oriented starter | Yes | +| `audit ` | Run token-drift and accessibility-basics validators | No | +| `review ` | Report static design risks; optionally create a fix prompt | No | +| `visual ` | Create screenshot/static visual QA evidence | Yes | +| `elevate ` | Generate a premium-refactor prompt | Yes | +| `report ` | Create a delivery report and sign-off ledger | Yes | +| `eval ` | Scaffold a controlled evaluation run | Yes | +| `case ` | Scaffold a case study and showcase entry | Yes | -🖼 **[The showcase gallery](examples/README.md)** — four complete pages (landing, -dashboard, pricing, docs) for one fictional product, all on a single token system. -Every page has its decision paper-trail: -[landing](examples/saas-landing-walkthrough.md) · [dashboard](examples/dashboard-walkthrough.md) · -[pricing](examples/pricing-walkthrough.md) · [docs](examples/docs-walkthrough.md) — -**including the real failures the loop caught before delivery** (a dark-theme contrast -miss, an unverified metric, a CSS cascade bug found at 577px). +```bash +node DesignOS/bin/designos.js doctor +node DesignOS/bin/designos.js export all +node DesignOS/bin/designos.js brief --interactive +node DesignOS/bin/designos.js starter landing-page my-launch +node DesignOS/bin/designos.js audit src/ +node DesignOS/bin/designos.js review src/ --fix-prompt --no-fail +node DesignOS/bin/designos.js visual index.html --no-fail +node DesignOS/bin/designos.js elevate src/ --no-fail +node DesignOS/bin/designos.js report src/ --no-fail +node DesignOS/bin/designos.js eval cursor-pricing --agent Cursor --brief B-001 +node DesignOS/bin/designos.js case acme-pricing --project "Acme Pricing" --url https://example.com +``` -🔬 **[Measure it yourself](evals/README.md)** — 10 fixed briefs, a paste-ready -[neutral judge prompt](evals/judge-prompt.md), validators as the objective floor, a -[run report template](evals/RUN_TEMPLATE.md), and [published results](evals/RESULTS.md) -with the caveats stated plainly. -External runs should follow the [independent run guide](evals/independent-run-guide.md) -and the [Run 003 call](evals/run-003-call-for-evals.md). The first maintainer-observed -agent run is documented at [Run 003 — Antigravity Pricing](evals/runs/run-003-antigravity-pricing/). +Run `node DesignOS/bin/designos.js help` for flags and usage. The CLI has no runtime +dependencies beyond Node.js 18+. -🌐 **[The website](website/index.html)** — designed by the system it documents. -View source: every value resolves to a token. +--- -🤖 **[The live-proof pipeline](.github/workflows/proof.yml)** ([latest run](https://github.com/ardamoustafa1/DesignOS/actions/workflows/proof.yml)) — -runs the real installer end-to-end on every push, then renders the site and every -showcase page in a headless browser and checks for console errors. It's CI, not a -video — but unlike a video it can't go stale: if a change breaks the install or a page -throws an error, the badge at the top of this file turns red the same day. +## Quality and evidence -🧪 **[The DesignOS Review Action](actions/README.md)** — drop-in PR review for UI files: -contrast risk, missing states, fake proof, token drift, a11y tells, and a six-dimension -gate score without calling a model. +DesignOS reviews seven dimensions. The written rubric sets the quality language; the +evidence ledger records which checks actually happened. + +| Dimension | What the reviewer attacks | Typical evidence | +|---|---|---| +| UI Craft | Type, spacing, color, alignment, tokens, detail consistency | Source inspection + rendered viewports | +| UX & Flow | Eye path, cognitive load, conventions, state completeness | Flow walk + responsive/state evidence | +| Accessibility | Contrast, keyboard, semantics, reflow, announcements, motion | Tools + manual keyboard/tree checks | +| Performance | LCP, CLS, INP, payloads, fonts, images, animation cost | Lighthouse/CWV measurement | +| Modernity | Current craft without trend cosplay | Reference comparison + creative review | +| Conversion | Claim, mechanism, proof, objections, ask, friction, honesty | Content/proof audit + task completion | +| Brand Fit & Distinctiveness | Product derivation, signature, swap resistance | Derivation chain + logo-swap/recall review | + +```mermaid +flowchart LR + A["Source checks"] --> E["Evidence ledger"] + B["Rendered viewports"] --> E + C["Keyboard · a11y · motion"] --> E + D["Performance + human review"] --> E + E --> F{"Every applicable row assessed?"} + F -- "No" --> G["Report NOT ASSESSED"] + F -- "Yes" --> H["Apply scoring rubric"] +``` + +> [!IMPORTANT] +> A clean static `review` result means the configured source-risk checks found nothing. +> It does not by itself prove WCAG conformance, visual excellence, Lighthouse scores, or +> conversion performance. Read [Proof Standard](PROOF_STANDARD.md), [Final Gate](workflows/final-gate.md), +> and [Known Limitations](LIMITATIONS.md) before publishing a quality claim. + +### What is mechanically checked today? + +- token drift and off-grid spacing risks +- common semantic and accessible-name mistakes +- missing landmarks/headings and suspicious focus removal +- raw color usage outside token/exception boundaries +- common fake-proof and hard-compliance claim risks +- thin state coverage heuristics +- optional browser screenshots and basic overflow/render checks + +The complete design review remains broader than these static checks. Unverified dimensions +stay **NOT ASSESSED** rather than becoming an invented score. --- -## The Review Engine +## Examples and starters -Nothing ships on vibes. Every deliverable is scored against a -[written rubric](scoring/rubric.md): +### See the system applied -| Dimension | Gate | | -|---|---|---| -| UI Craft | ≥ 95 | typography, spacing, color, detail discipline | -| UX & Flow | ≥ 95 | hierarchy, cognitive load, state completeness | -| Accessibility | ≥ 95 | **AA failures cap the score at 60 — no negotiation** | -| Performance | ≥ 95 | LCP < 2.0s · CLS < 0.1 · INP < 200ms | -| Modernity | ≥ 95 | current-year professional, zero trend cosplay | -| Conversion | ≥ 95 | **fake proof & dark patterns = instant fail** | +| Resource | What to inspect | +|---|---| +| [Before / After](website/before-after.html) | The same brief with visible anti-pattern annotations | +| [Live showcase](examples/README.md) | Landing, dashboard, pricing, and docs on one token system | +| [Landing walkthrough](examples/saas-landing-walkthrough.md) | Decisions and failures behind the landing page | +| [Dashboard walkthrough](examples/dashboard-walkthrough.md) | Density, hierarchy, tables, charts, and states | +| [Pricing walkthrough](examples/pricing-walkthrough.md) | Plan choice, trust, proof, and conversion logic | +| [Docs walkthrough](examples/docs-walkthrough.md) | Information architecture and developer experience | +| [Goldens](goldens/README.md) | Target bars for premium output categories | +| [Anti-Pattern Museum](museum/README.md) | Recognizable design failures and preventing rules | -Under threshold → back to the loop with specific objections, *before you ever see it*. +### Start with working files + +```bash +node DesignOS/bin/designos.js starter list +node DesignOS/bin/designos.js starter landing-page my-launch +node DesignOS/bin/designos.js starter next-saas my-app +node DesignOS/bin/designos.js starter react-dashboard operations-console +node DesignOS/bin/designos.js starter docs-site developer-docs +node DesignOS/bin/designos.js starter mobile-app mobile-onboarding +``` + +Browse [all starters](starter/README.md), [copy-ready recipes](recipes/README.md), +[visual reference packs](references/README.md), and the one-page [cheatsheet](CHEATSHEET.md). --- -## Philosophy +## Troubleshooting -- **Taste is teachable.** Encoded as rules, references, and anti-patterns — not adjectives. -- **Process beats talent.** The loop catches what inspiration misses. -- **Self-criticism is a feature.** The reviewer agent is paid to say no. -- **Memory compounds.** Decision #40 should be consistent with decision #4. -- **Honesty is enforced, not suggested.** Invented metrics and dark patterns fail the build. -- **Every rule earns its place.** If a rule can't cite a reason, it gets deleted. +
+The agent ignores DesignOS + +Run `doctor`. Confirm the correct rules file exists for your agent and that `./DesignOS` +has not been moved. For Claude Code, `CLAUDE.md` must contain `@DesignOS/CLAUDE.md`. + +
+ +
+The output still looks generic + +Give the brief product material, real assets, a brand belief, and a never-list. Ask the +agent to show the three design directions before implementation and name the chosen +signature's derivation chain. See [Brief Compiler](brain/brief-compiler.md) and +[Originality](brain/originality.md). + +
+ +
+The CLI says the target does not exist + +Run commands from the project root and pass a path relative to that root. `review` accepts +supported UI source files or directories; `visual` expects an HTML file or URL. + +
+ +
+An export would overwrite my existing rules + +DesignOS protects non-generated rules files. Merge the instructions intentionally or back +up the file before using `--force`. See [integrations](integrations/README.md). + +
+ +
+I accidentally ran npx designos + +That package is unrelated. Review any changes it made, then reinstall with +`npx github:ardamoustafa1/DesignOS init --agents --skills` and use the local Node command. + +
+ +For a longer onboarding and diagnostic guide, read [Getting Started](GETTING-STARTED.md). + +--- ## Community -- ⭐ **Star the repo** — it's how other builders find it -- 🏗 **[Add your work to the Showcase](SHOWCASE.md)** — and take the - [![badge](https://img.shields.io/badge/designed%20with-DesignOS-10b981)](SHOWCASE.md) with you -- 🥊 **[Challenge a rule](CONTRIBUTING.md)** — every rule stands on evidence; bring yours -- 🔍 **[Run the missing independent eval](evals/RUN_TEMPLATE.md)** — the single highest-value - contribution available right now -- 💬 **[Discussions](DISCUSSIONS.md)** — questions, show-and-tell, module ideas (setup guide; enable in repo Settings) -- 🗺 **[Roadmap](ROADMAP.md)** · 🚀 **[Launch playbook](LAUNCH.md)** · 🛡 **[Security](SECURITY.md)** · 📰 **[Press kit](press/README.md)** · ⚠️ **[Known limitations](LIMITATIONS.md)** · 🏢 **[Enterprise](ENTERPRISE.md)** · ⚖️ **[Governance](GOVERNANCE.md)** +DesignOS becomes more credible through inspectable work, independent runs, and challenged +rules — not through louder claims. + +- Star the repository so other builders can find it. +- Add real work to the [Showcase](SHOWCASE.md). +- Submit an independent result using the [evaluation protocol](evals/README.md). +- Challenge or sharpen a rule through [Contributing](CONTRIBUTING.md). +- Share a real adoption story using the [case-study template](case-studies/TEMPLATE.md). +- Join [Discussions](DISCUSSIONS.md) for questions, show-and-tell, and module proposals. + +Project guides: [Roadmap](ROADMAP.md) · [Security](SECURITY.md) · +[Enterprise](ENTERPRISE.md) · [Governance](GOVERNANCE.md) · +[Code of Conduct](CODE_OF_CONDUCT.md) · [Press kit](press/README.md) + +--- ## License -MIT — see [LICENSE](LICENSE). Use it, fork it, ship with it. +MIT — see [LICENSE](LICENSE). Use it, fork it, adapt it, and document what you learn.
-Built for the age of agents. Designed to make them dangerous. + +**Build interfaces that can explain every decision.** + +DesignOS is open source. The strongest contribution is evidence from real use. +
diff --git a/bin/designos.js b/bin/designos.js index 5320db4f..f6fa0c1b 100644 --- a/bin/designos.js +++ b/bin/designos.js @@ -309,7 +309,7 @@ function analyzeDesignFile(absFile, root) { pushFinding(findings, rel, lineOf(raw, m.index), 'Accessibility', 'P1', 'img-no-alt', 'Image is missing alt text.'); } for (const m of raw.matchAll(/<(button|a)\b([^>]*)>(\s*)<\/\1>/gi)) { - pushFinding(findings, rel, lineOf(raw, m.index), 'UX Flow', 'P1', 'empty-control', 'Interactive control has no visible label.'); + pushFinding(findings, rel, lineOf(raw, m.index), 'UX & Flow', 'P1', 'empty-control', 'Interactive control has no visible label.'); } for (const m of raw.matchAll(/<(div|span)\b[^>]*\bonclick=/gi)) { pushFinding(findings, rel, lineOf(raw, m.index), 'Accessibility', 'P1', 'nonsemantic-click', `${m[1]} uses onclick; prefer a semantic button/link.`); @@ -318,7 +318,7 @@ function analyzeDesignFile(absFile, root) { pushFinding(findings, rel, 1, 'Accessibility', 'P2', 'missing-main', 'HTML page has no
landmark.'); } if (absFile.endsWith('.html') && !/]/i.test(raw)) { - pushFinding(findings, rel, 1, 'UX Flow', 'P2', 'missing-h1', 'HTML page has no

; hierarchy may be unclear.'); + pushFinding(findings, rel, 1, 'UX & Flow', 'P2', 'missing-h1', 'HTML page has no

; hierarchy may be unclear.'); } for (const m of raw.matchAll(/#[0-9a-fA-F]{3,8}\b/g)) { @@ -381,7 +381,7 @@ function analyzeDesignFile(absFile, root) { } if (isUiSurface && / [d, 100])); + const assessedDims = ['UI Craft', 'UX & Flow', 'Accessibility', 'Modernity', 'Conversion']; + const staticRiskScores = Object.fromEntries(assessedDims.map(d => [d, 100])); const weights = { P0: 25, P1: 12, P2: 5 }; + const blockerCodes = new Set([ + 'img-no-alt', 'empty-control', 'nonsemantic-click', 'focus-removed', + 'proof-risk', 'customer-proof-risk', 'quote-proof-risk', 'placeholder-copy', + ]); for (const f of findings) { - scores[f.dimension] = Math.max(0, scores[f.dimension] - weights[f.severity]); + staticRiskScores[f.dimension] = Math.max(0, staticRiskScores[f.dimension] - weights[f.severity]); + if (blockerCodes.has(f.code)) staticRiskScores[f.dimension] = Math.min(60, staticRiskScores[f.dimension]); } - const overall = Math.min(...Object.values(scores)); - return { filesReviewed: files.length, findingCount: findings.length, scores, overall }; + const staticRiskFloor = Math.min(...Object.values(staticRiskScores)); + const unassessed = [ + 'visual hierarchy and brand fit', 'keyboard completion', 'accessibility tree and screen reader', + 'computed contrast across real states', '320px reflow/400% zoom', 'reduced motion', + 'Lighthouse/Core Web Vitals', 'task completion and conversion quality', + ]; + return { + filesReviewed: files.length, + findingCount: findings.length, + status: findings.length ? 'FINDINGS' : 'STATIC CHECKS CLEAN', + finalScore: 'NOT ASSESSED', + staticRiskScores, + staticRiskFloor, + unassessed, + }; } function printReviewMarkdown(report) { console.log('# DesignOS Review\n'); console.log(`Files reviewed: ${report.summary.filesReviewed}`); console.log(`Findings: ${report.summary.findingCount}`); - console.log(`Overall gate: ${report.summary.overall}/100\n`); - console.log('| Dimension | Score |'); + console.log(`Static risk floor: ${report.summary.staticRiskFloor}/100 (not a final design score)`); + console.log(`Final design score: ${report.summary.finalScore}\n`); + console.log('| Dimension | Static risk indicator |'); console.log('|---|---:|'); - for (const [dim, score] of Object.entries(report.summary.scores)) { + for (const [dim, score] of Object.entries(report.summary.staticRiskScores)) { console.log(`| ${dim} | ${score} |`); } + console.log(`\nNot assessed: ${report.summary.unassessed.join('; ')}.`); if (!report.findings.length) { console.log('\nNo deterministic findings. Run the human/model review loop for taste, hierarchy, and fit.'); return; @@ -438,7 +458,8 @@ function fixAdviceFor(f) { function printFixPrompt(report, min) { console.log('Fix these DesignOS review findings, then rerun the DesignOS loop.'); console.log(`Target: ${report.target}`); - console.log(`Current gate: ${report.summary.overall}/100. Required gate: ${min}/100.\n`); + console.log(`Current static risk floor: ${report.summary.staticRiskFloor}/100. Requested mechanical floor: ${min}/100.`); + console.log('Final design score: NOT ASSESSED until the manual/browser evidence ledger is complete.\n'); console.log('Rules:'); console.log('- Do not trust the agent self-score; the final pass is this deterministic review output.'); console.log('- Do not invent customers, testimonials, certifications, usage counts, awards, urgency, or compliance claims.'); @@ -470,7 +491,7 @@ function review(target, args) { if (fixPrompt) printFixPrompt(report, min); else if (asJson) console.log(JSON.stringify(report, null, 2)); else printReviewMarkdown(report); - if (!noFail && summary.overall < min) process.exit(1); + if (!noFail && summary.staticRiskFloor < min) process.exit(1); } function buildReviewReport(target) { @@ -491,12 +512,13 @@ function markdownForReviewReport(report) { `Generated: ${report.generatedAt}`, `Files reviewed: ${report.summary.filesReviewed}`, `Findings: ${report.summary.findingCount}`, - `Overall gate: ${report.summary.overall}/100`, + `Static risk floor: ${report.summary.staticRiskFloor}/100 (not a final design score)`, + `Final design score: ${report.summary.finalScore}`, '', - '| Dimension | Score |', + '| Dimension | Static risk indicator |', '|---|---:|', ]; - for (const [dim, score] of Object.entries(report.summary.scores)) { + for (const [dim, score] of Object.entries(report.summary.staticRiskScores)) { lines.push(`| ${dim} | ${score} |`); } lines.push('', '## Findings', ''); @@ -515,7 +537,8 @@ function report(target, args) { '', `Target: ${target}`, `Generated: ${new Date().toISOString()}`, - `Gate: ${reviewReport.summary.overall}/100 (required ${min}/100)`, + `Static risk floor: ${reviewReport.summary.staticRiskFloor}/100 (requested ${min}/100)`, + 'Final design score: NOT ASSESSED until sign-off evidence is completed', '', '## Review Gate', '', @@ -535,7 +558,10 @@ function report(target, args) { '', '## Sign-off Checklist', '', + '- [ ] 320px reflow / 400% zoom inspected', '- [ ] Mobile 375px inspected', + '- [ ] Tablet 768px inspected', + '- [ ] Laptop 1024px inspected', '- [ ] Desktop 1440px inspected', '- [ ] Keyboard-only path verified', '- [ ] Reduced-motion mode verified', @@ -545,7 +571,7 @@ function report(target, args) { ].join('\n'); fs.writeFileSync(outPath, sections); ok(`Delivery report written to ${path.relative(CWD, outPath)}`); - if (!args.includes('--no-fail') && reviewReport.summary.overall < min) process.exit(1); + if (!args.includes('--no-fail') && reviewReport.summary.staticRiskFloor < min) process.exit(1); } /* ---------- elevate: premium refactor prompt for better-than-clean UI ---------- */ @@ -692,7 +718,7 @@ function elevate(target, args) { ]; fs.writeFileSync(outPath, lines.join('\n')); ok(`Elevation prompt written to ${path.relative(CWD, outPath)}`); - if (reviewReport.summary.overall < min && !args.includes('--no-fail')) process.exit(1); + if (reviewReport.summary.staticRiskFloor < min && !args.includes('--no-fail')) process.exit(1); } /* ---------- brief: generate a high-signal DesignOS brief ---------- */ @@ -758,11 +784,11 @@ function brief(args) { '', 'Required process:', '- State which DesignOS modules you are loading and why.', - '- Run research -> wireframe -> UI -> review -> accessibility -> performance -> refactor.', - '- Score UI Craft, UX Flow, Accessibility, Performance, Modernity, and Conversion.', - '- Run the deterministic final gate before claiming a score: review, elevate, visual, then report.', + '- Compile the design contract, compare directions, then run research -> wireframe -> UI -> render/inspect -> review -> accessibility -> performance -> refactor.', + '- Score UI Craft, UX & Flow, Accessibility, Performance, Modernity, Conversion, and Brand Fit & Distinctiveness.', + '- Run the static risk gate and complete the evidence ledger before claiming a score: review, elevate, visual, then report.', '- Redo any dimension under 95 before delivery.', - '- Do not claim 95+, 100/100, zero findings, or SHIP unless the deterministic review output proves it.', + '- Do not claim 95+, 100/100, zero findings, or SHIP while any applicable evidence row is NOT ASSESSED.', '- Do not invent metrics, customers, testimonials, badges, urgency, or compliance claims.', '- Do not claim SOC2, ISO 27001, HIPAA, PCI, GDPR, FIPS, audited, or certified unless a real source is linked.', '- Write durable decisions to memory/ after delivery.', @@ -776,7 +802,7 @@ function brief(args) { '```', '', 'Deliverable:', - '- A production-ready artifact plus deterministic gate output, scorecard, key decisions, and remaining risks.', + '- A production-ready artifact plus static gate output, evidence ledger, scorecard or NOT ASSESSED labels, key decisions, and remaining risks.', ].join('\n'); const outPath = argValue(args, '--out', ''); if (outPath) { @@ -1069,7 +1095,7 @@ function caseStudy(slug, args) { '| Dimension | Score | Evidence |', '|---|---:|---|', '| UI Craft | TODO | TODO |', - '| UX Flow | TODO | TODO |', + '| UX & Flow | TODO | TODO |', '| Accessibility | TODO | TODO |', '| Performance | TODO | TODO |', '| Modernity | TODO | TODO |', diff --git a/brain/brief-compiler.md b/brain/brief-compiler.md new file mode 100644 index 00000000..079d3722 --- /dev/null +++ b/brain/brief-compiler.md @@ -0,0 +1,102 @@ +# Brief Compiler — Turn Requests into Design Contracts + +Great output is usually won before the first component is drawn. This module converts a +loose request into a compact, testable design contract without turning intake into an +interview marathon. Run it after `brain/decision-framework.md` and before task routing. + +## The contract + +Compile every design request into these fields. Read project memory first; ask only for +missing information that would materially change the result. Otherwise use the 70% rule, +label the assumption, and continue. + +| Field | Decision it controls | Minimum usable answer | +|---|---|---| +| Intent | hierarchy and primary action | one behavior the surface must cause | +| Reader | density, language, proof | role, expertise, emotional state, likely device | +| Job and doubt | flow and objection handling | top job plus the moment confidence drops | +| Product material | inspectable artifact and signature | real inputs, outputs, data shapes, workflow, or object | +| Proof inventory | trust strategy | verified assets, unavailable proof, claim level from `PROOF_STANDARD.md` | +| Asset inventory | composition | screenshots, brand assets, photography, illustration, and their quality | +| Brand belief | copy and art direction | a specific opinion the product can credibly own | +| Never-list | anti-template constraints | clichés, competitors, tones, colors, or patterns to avoid | +| Constraints | implementation | stack, target files, themes, locales, performance, legal, timeline | +| Acceptance | completion | breakpoints, states, task success, measured checks, required gate | + +## Originality synthesis + +Do not ask the user to invent a visual style. Derive three meaningfully different +directions from their material: + +1. **Material-led** — turn a real product object, workflow, data shape, or transformation + into the hero and recurring visual language. +2. **Audience-led** — borrow a credible structure or texture from the reader's working + world, not from the sector's most common landing-page template. +3. **Belief-led** — express the brand's specific point of view through type voice, + composition, copy rhythm, or one interaction. + +For a full page or expensive-to-reverse system, compare all three. Score each direction +against intent, clarity, product truth, distinctiveness, accessibility, and performance. +Choose one and record why in `memory/design.md`. For a small component, one derived +direction is enough; do not manufacture three cosmetic variants. + +The chosen direction declares: + +- **signature vehicle** — type, product artifact, layout gesture, motion, data language, + copy voice, or image system; +- **derivation chain** — product/audience/belief fact → design move → user benefit; +- **repetition rule** — where the signature returns so it becomes a language; +- **cost guard** — how it avoids usability, accessibility, and performance debt; +- **anti-clone check** — which reference tactic is transferred and which branded motif + is explicitly prohibited. + +## Prompt assembly + +Use this order when producing an agent-ready prompt. Constraints placed after visual +requests are often ignored; the contract comes first. + +```text +ROLE AND OUTCOME +Act as DesignOS. Cause: . Reader: . + +TRUTH AND MATERIAL +Product material: . Verified proof: . +Unavailable or forbidden claims: . Assets: . + +DIRECTION +Brand belief: . Never-list: . +Chosen signature: . Derivation: move -> benefit>. + +SCOPE AND CONSTRAINTS +Target: . Stack: . Breakpoints/themes/locales: . +Required states: . Performance/legal constraints: . + +PROCESS +Boot the kernel; route only relevant modules; run the Design Loop; render and inspect +applicable viewports; run the deterministic Final Gate when a file target exists. + +DELIVERY +Artifact + verification evidence + deterministic result (or clearly labeled self-review) ++ rationale + project-memory updates. Never claim a pass for an unmeasured check. +``` + +## Anti-patterns + +- Adjective briefs: "premium, modern, beautiful" without material, audience, or truth. +- Reference cosplay: "make it Linear" without naming a transferable tactic and a + prohibited brand-specific motif. +- Fake specificity: inventing metrics, logos, testimonials, compliance, or product UI to + make a sparse brief feel complete. +- Intake theater: blocking on low-impact questions instead of using labeled assumptions. +- Prompt inflation: pasting every module into the prompt; route only what changes action. +- Variant theater: three versions that differ only by color, radius, or gradient. + +## Checklist + +- [ ] Contract names intent, reader state, product material, proof, assets, belief, + never-list, constraints, and acceptance evidence +- [ ] Missing facts are either asked once or recorded as labeled assumptions +- [ ] Full-page direction choice compares three structurally distinct hypotheses +- [ ] Signature includes a derivation chain, repetition rule, cost guard, and anti-clone check +- [ ] Prompt boots the kernel and requires render inspection plus the Final Gate +- [ ] No unverified claim, alternate mini-kernel, or unnecessary module dump remains diff --git a/brain/trend-radar.md b/brain/trend-radar.md index 7f7b8b46..8678ace7 100644 --- a/brain/trend-radar.md +++ b/brain/trend-radar.md @@ -1,5 +1,8 @@ # Trend Radar — Currency Without Cosplay +**Last reviewed:** 2026-07-17 · **Review cadence:** quarterly · **Next review due:** 2026-10-17 +When overdue, treat CURRENT entries as hypotheses and do not use them as sole justification. + The Modernity dimension (`scoring/rubric.md`) demands work that reads *current-year professional*. This module is the radar: what signals fresh, what signals dated, what signals template — and the discipline for telling trend from principle. diff --git a/checklists/accessibility.md b/checklists/accessibility.md index cd772f4c..9e840a0b 100644 --- a/checklists/accessibility.md +++ b/checklists/accessibility.md @@ -13,6 +13,7 @@ protocol. Any unchecked box in the BLOCKER sections = audit FAIL = dimension cap ## Keyboard — BLOCKERS - [ ] Tab reaches every interactive element; order = visual order - [ ] Focus visible at every stop (styled `:focus-visible`, ≥3:1, never `outline:none` bare) +- [ ] Focus is not obscured by sticky headers, cookie banners, drawers, or overlays (2.4.11) - [ ] No traps; Esc closes every overlay; focus returns to trigger - [ ] Skip link first, functional, visible on focus - [ ] Dropdowns/menus/tabs: arrow keys, Enter/Space, Esc per pattern @@ -23,6 +24,8 @@ protocol. Any unchecked box in the BLOCKER sections = audit FAIL = dimension cap - [ ] Landmarks: header/nav/main/footer; exactly one main - [ ] Buttons are `