{"id":"fc2f0a6b-9bf7-4b0f-8559-f6dccc9d4790","entityType":"agent","slug":"clawhub-grubbylee-f-design-2","name":"Design Guide","canonicalUrl":"https://www.xpersona.co/agent/clawhub-grubbylee-f-design-2","canonicalPath":"/agent/clawhub-grubbylee-f-design-2","generatedAt":"2026-10-09T23:51:41.573Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":null},"description":"Frontend design, implementation, and production QA Skill: Design Guide Owner: grubbylee Summary: Frontend design, implementation, and production QA Tags: latest:0.1.2 Version history: v0.1.2 | 2026-08-08T16:10:13.728Z | auto - Initial release of f-design-2 v0.1.2 as \"design-guide\": a comprehensive frontend design and production engineering orchestrator. - Introduces structured reference routing for design, implementation, review, and environment-specific decisions. -","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s177gc2ae6jagj5ta42ajajrfs8bqm1t:f-design-2","sourceUrl":"https://clawhub.ai/grubbylee/f-design-2","homepage":"https://clawhub.ai/grubbylee/skills/f-design-2","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/grubbylee/f-design-2","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/grubbylee/skills/f-design-2","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":67,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Frontend design, implementation, and production QA Skill: Design Guide Owner: grubbylee Summary: Frontend design, implementation, and production QA Tags: latest"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":null},"stars":null,"forks":null,"downloads":2346,"packageName":null,"latestVersion":"0.1.2","tractionLabel":"2.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T16:06:17.413Z","lastCrawledAt":"2026-10-09T16:06:17.413Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T16:06:17.413Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.2","createdAt":"2026-08-08T16:10:13.728Z","changelog":"- Initial release of f-design-2 v0.1.2 as \"design-guide\": a comprehensive frontend design and production engineering orchestrator. - Introduces structured reference routing for design, implementation, review, and environment-specific decisions. - Adds invocation modes: Navigation (frontend entry/menu and tool suggestion) and Execution (artifact-driven design-to-production flows). - Provides task routing and workflow examples for various frontend challenges, from UI builds to design reviews and taste corrections. - Defines context-sensitive helper and preference file lookup for tailored output. - Focuses on modularity, environment/tool neutrality, and explicit review/approval flow before implementation.","fileCount":92,"zipByteSize":136142}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177gc2ae6jagj5ta42ajajrfs8bqm1t:f-design-2","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T23:51:41.571Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-grubbylee-f-design-2/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":null},"readme":"Skill: Design Guide\n\nOwner: grubbylee\n\nSummary: Frontend design, implementation, and production QA\n\nTags: latest:0.1.2\n\nVersion history:\n\nv0.1.2 | 2026-08-08T16:10:13.728Z | auto\n\n- Initial release of f-design-2 v0.1.2 as \"design-guide\": a comprehensive frontend design and production engineering orchestrator.\n- Introduces structured reference routing for design, implementation, review, and environment-specific decisions.\n- Adds invocation modes: Navigation (frontend entry/menu and tool suggestion) and Execution (artifact-driven design-to-production flows).\n- Provides task routing and workflow examples for various frontend challenges, from UI builds to design reviews and taste corrections.\n- Defines context-sensitive helper and preference file lookup for tailored output.\n- Focuses on modularity, environment/tool neutrality, and explicit review/approval flow before implementation.\n\nArchive index:\n\nArchive v0.1.2: 92 files, 136142 bytes\n\nFiles: .github (0b), .github/workflows (0b), .github/workflows/sync-to-gitee.yml (1410b), .github/workflows/validate.yml (4302b), .gitignore (94b), agents (0b), agents/openai.yaml (284b), assets (0b), assets/design-guide-logo-dark.svg (697b), assets/design-guide-logo-light.svg (697b), assets/design-guide-mark.svg (443b), CHANGELOG.md (2633b), CHANGELOG.zh-CN.md (1159b), COMPATIBILITY.md (1132b), COMPATIBILITY.zh-CN.md (504b), design-guide.json (660b), LICENSE (1062b), locales (0b), locales/en.json (6707b), locales/zh-CN.json (6692b), README.md (15534b), README.zh-CN.md (14603b), references (0b), references/aide-integration.md (4278b), references/anti-ai-design-tells.md (4185b), references/artifact-presentation.md (3864b), references/design-contract.schema.json (4811b), references/design-defaults.md (2574b), references/design-process.md (5237b), references/end-to-end-journeys.md (2952b), references/framework-adapters.md (2676b), references/helper-registry.md (2933b), references/implementation-contract.md (2145b), references/internationalization.md (2023b), references/internationalization.zh-CN.md (1864b), references/local-overrides.example.md (1110b), references/product-design-review.md (15396b), references/project-intelligence.md (1743b), references/project-profile.example.md (1116b), references/quality-gates.md (2909b), references/review-rubric.md (3007b), references/review-templates (0b), references/review-templates/complex-forms.md (1637b), references/review-templates/dashboards.md (1474b), references/review-templates/data-tables.md (1559b), references/review-templates/high-risk-batch-actions.md (1744b), references/review-templates/mobile-navigation.md (1576b), references/state-and-data.md (2040b), RELEASE_NOTES.md (1931b), RELEASE_NOTES.zh-CN.md (316b), scripts (0b), scripts/capture-audit.py (2639b), scripts/check-secrets.py (2863b), scripts/design-contract.py (13954b), scripts/design-guide-doctor.py (7316b), scripts/detect-frontend-env.sh (2752b), scripts/evaluate-review-output.py (3975b), scripts/i18n.py (2742b), scripts/inspect-project.py (11205b), scripts/present-design.py (16891b), scripts/run-preview.py (12504b), scripts/smoke-aides.py (4493b), scripts/sync-aide.sh (2524b), scripts/verify-product-journeys.py (3485b), scripts/verify-ui.py (17334b), scripts/visual-diff.py (3720b), skill-card.md (3043b), SKILL.md (19927b), SKILL.zh-CN.md (2769b), tests (0b), tests/fixtures (0b), tests/fixtures/quality (0b), tests/fixtures/quality/design-contract.json (2140b), tests/fixtures/quality/index.html (1734b), tests/fixtures/quality/review-artifact.html (224b), tests/fixtures/review-behavior (0b), tests/fixtures/review-behavior/desktop-url-isolated-pass.md (476b), tests/fixtures/review-behavior/desktop-url-isolated.json (462b), tests/fixtures/review-behavior/image-review-inherited-fail.md (380b), tests/fixtures/review-behavior/image-review-isolated-pass.md (431b)\n\nFile v0.1.2:SKILL.md\n\n---\nname: design-guide\ndescription: Frontend design and production engineering orchestrator that inventories projects, scales design depth, presents review artifacts, locks executable contracts, implements accessible responsive interfaces, and verifies interactions, visual regressions, and performance. Use when the user invokes design-guide, @design-guide, /design-guide, asks for frontend design/development/redesign, web app UI, dashboard, tool interface, landing page, responsive React/HTML/CSS work, design previews or choices, screenshot QA, production frontend quality, or says they are dissatisfied with generic AI-looking UI. If invoked without a concrete task, enter navigation mode and recommend the best available frontend-related skills/tools for the user's environment instead of coding.\n---\n\n# F Design\n\nUse this as the frontend entry skill. It is not a single visual style; it controls product thinking, approval, implementation, and production verification.\n\n## Reference Routing\n\nRead only the references required by the task:\n\n- Existing repository or substantial implementation: `references/project-intelligence.md`.\n- New screen, major redesign, ambiguous direction, or workflow change: `references/design-process.md`.\n- Any artifact created for user review: `references/artifact-presentation.md`.\n- Approved Level 2 or multi-state/multi-route implementation: `references/implementation-contract.md`.\n- API, form, permissions, async, mutation, or non-trivial state: `references/state-and-data.md`.\n- Stack-specific implementation decisions: matching section of `references/framework-adapters.md`.\n- Substantial implementation verification: `references/quality-gates.md`.\n- UI/UX review request: `references/review-rubric.md`.\n- Existing product/page design evaluation, pros/cons critique, or actionable improvement report: `references/product-design-review.md`, `references/review-rubric.md`, and `references/anti-ai-design-tells.md` when visual quality or generic AI-looking UI is in scope.\n- Specialized review targets: use the matching file under `references/review-templates/` for data tables, dashboards, complex forms, mobile navigation, or high-risk batch actions.\n- Release-level workflow verification or maintainer work: `references/end-to-end-journeys.md`.\n- Internationalization, CLI language selection, or translated maintainer docs: `references/internationalization.md`.\n\n## Context Files\n\nBefore substantial work, look for preference files in this order:\n\n1. `.design-guide/profile.md` in the current project.\n2. `~/.design-guide/preferences.md` on the local machine.\n3. `references/design-defaults.md` bundled with this skill.\n\nRead only the files that exist and are relevant. Project and local files override bundled defaults. Keep personal preferences out of the skill folder so the skill remains open-source friendly.\n\n## Invocation Modes\n\n### Mode 1: Navigation\n\nUse this mode when the user only says `design-guide`, `@design-guide`, `/design-guide`, \"use design-guide\", or otherwise gives no concrete frontend task.\n\nReply with a concise menu of what the environment can do. Do not code. Do not invent unavailable skills.\n\n1. Inspect the available skill/tool list if the host exposes one.\n2. Read `references/helper-registry.md`.\n3. Group relevant capabilities by task, not by skill name.\n4. Recommend the best primary path and optional helpers.\n5. Give 2-3 example prompts the user can run next.\n\nNavigation output should look like:\n\n```text\ndesign-guide is ready. Pick a frontend task:\n\n1. Build a product screen / dashboard / tool\n Primary: design-guide\n Helpers if available: web-design-engineer, webapp-testing\n\n2. Improve visual taste of an existing page\n Primary: design-guide\n Helpers if available: design-taste-frontend, web-design-guidelines\n\n3. Evaluate an existing product/page design\n Primary: design-guide\n Helpers if available: web-design-guidelines, webapp-testing, design-taste-frontend\n\n4. Add complex animation\n Primary: design-guide\n Helpers if available: gsap, animejs\n\n5. Build 3D / WebGL\n Primary: design-guide\n Helpers if available: three\n```\n\nIf a helper is not visible in the current AIDE, say \"not detected here\" and continue with the best fallback.\n\n### Mode 2: Execution\n\nUse this mode when the user gives a real frontend task.\n\nDo not start coding immediately unless the task is a tiny isolated UI fix. First choose the design depth, produce and present the required design artifacts, and resolve any approval gate. For substantial work, build a viewable v0 before completing the full interface.\n\nUse the reference routing above. A file is not presented until the user can immediately inspect it.\n\n## Task Routing\n\nRoute the user's wording before selecting tools:\n\n- \"build a dashboard/admin/tool/editor\" -> product screen workflow; make the usable working surface first.\n- \"make this prettier/redesign/looks AI-generated\" -> taste correction workflow; preserve existing function and fix visual hierarchy.\n- \"match this screenshot/image\" -> screenshot-to-code workflow; use screenshot helpers if available.\n- \"landing page/site/homepage\" -> brand or landing workflow; verify product/brand facts when current or specific.\n- \"animation/motion/transition\" -> motion workflow; pick CSS/WAAPI/GSAP/Anime based on complexity and existing dependencies.\n- \"mobile/miniprogram/responsive\" -> mobile-first workflow; audit narrow widths before desktop polish.\n- \"review/audit/check UX/evaluate existing design/pros and cons/actionable improvements\" -> product design review workflow; read `references/product-design-review.md` and `references/review-rubric.md`; also read `references/anti-ai-design-tells.md` when visual quality, redesign, landing pages, dashboards, or generic AI-looking UI is in scope.\n\nFor existing product design reviews, start with a scope gate: state the explicit scope requested by the user and what is not included by default. Confirm expanded scope with the user before adding mobile/responsive, accessibility audits, redesigns, implementations, or downstream publishing goals. Then diagnose: classify the review mode, define product context, inspect the artifact, score strengths and weaknesses, and return prioritized, evidence-backed recommendations with implementation hints, tradeoffs, acceptance criteria, and verification steps. Do not redesign or implement unless the user asks for it or approves a proposed direction.\n\nLoad one specialized review template when the artifact requires it:\n\n- Data tables, queues, inventories, or admin grids -> `references/review-templates/data-tables.md`.\n- Analytics, monitoring, or decision dashboards -> `references/review-templates/dashboards.md`.\n- Multi-step, dependent, high-consequence, or long forms -> `references/review-templates/complex-forms.md`.\n- Mobile navigation -> `references/review-templates/mobile-navigation.md`, only when mobile is in scope.\n- Destructive, permissioned, publishing, financial, or multi-record mutations -> `references/review-templates/high-risk-batch-actions.md`.\n\n## AIDE Compatibility\n\nTreat `design-guide` as tool-neutral.\n\n- Codex: invoke with \"use design-guide\", `design-guide`, `$design-guide`, or `@design-guide` if the UI supports mentions.\n- Claude Code: invoke with `/design-guide` when the skill is installed in the Claude skill directory; natural language \"use design-guide\" is the fallback.\n- Cursor: invoke by asking the agent to use `design-guide` or by pointing it at this `SKILL.md`; if Cursor skill discovery is configured, install this folder under Cursor's skill directory.\n- Qwen Code: invoke by asking the agent to use `design-guide`; if Qwen skill discovery is configured, install this folder under Qwen's skill directory.\n- Other AIDE: use the same folder as a portable skill; if the tool has no skill protocol, tell the agent to read `SKILL.md` and follow `design-guide`.\n\nFor local setup details, read `references/aide-integration.md` only when the user asks about installing, syncing, or using this skill in another AIDE.\n\n## Language And Internationalization\n\nFollow `references/internationalization.md` when the user requests a language, translated instructions, or localized CLI output. Match the user's current request language by default. CLI helpers accept `--locale en|zh-CN` and resolve environment defaults through `F_DESIGN_LOCALE`, `LC_ALL`, and `LANG`. Keep JSON field names and machine-readable values stable in English; localize human-readable help, status, and error text only.\n\n## Workflow\n\n### 1. Read the product context\n\nState one line:\n\n```text\nReading this as: for , with a language, leaning toward .\n```\n\nInfer from the user request, repo, screenshots, existing CSS, `package.json`, named references, and business context. Ask one concise question only when the design direction genuinely splits.\n\nBefore substantial work in a codebase, read `references/project-intelligence.md` and run:\n\n```bash\npython3 scripts/inspect-project.py . --format markdown\n```\n\nInspect the reported entry routes, components, tokens, contracts, tests, scripts, and risks before selecting dependencies or files to edit. Use `scripts/detect-frontend-env.sh` only as a lightweight shell fallback.\n\n### 2. Choose the design depth\n\nClassify the work before producing artifacts:\n\n- Level 0 - direct fix: isolated visual or component-state correction; preserve the existing design contract.\n- Level 1 - directed design: established product structure and visual language; write a concise brief and layout/state outline.\n- Level 2 - exploratory design: new product or major screen, workflow or information-architecture change, major redesign, ambiguous direction, or brand-defining work; produce a reviewable artifact and require confirmation.\n\nUse the lightest level that resolves the uncertainty. State the chosen level and why in one sentence.\n\n### 3. Define the experience\n\nBefore visual styling, identify:\n\n- The user's primary job and most important workflow.\n- Information and action priority.\n- Required page regions, routes, states, and responsive behavior.\n- Product, brand, technical, accessibility, and content constraints.\n- Observable success criteria.\n\nFor API, form, permission, async, mutation, or state-heavy work, read `references/state-and-data.md` and map loading, empty, partial, error, success, permission, pending, retry, and rollback behavior as relevant. Use representative edge-case fixtures rather than happy-path-only demo data.\n\nFor Level 1, provide a compact design brief and layout/state outline. For Level 2, map the primary flow and information architecture before choosing a visual direction. Read `references/design-process.md` for the artifact and approval rules.\n\n### 4. Select helper capabilities\n\nBefore producing review artifacts or implementation, decide if auxiliary skills/tools are useful. Prefer the host's discovered names. Do not require the user to remember them. Read `references/helper-registry.md` when the selection is not obvious.\n\n- General polished web artifact: use `web-design-engineer` if available.\n- Landing page, portfolio, redesign taste correction: use `design-taste-frontend` if available.\n- UI audit, accessibility, best-practice review: use `web-design-guidelines` if available.\n- Browser screenshot/testing: use `webapp-testing` or local Playwright.\n- Complex motion: use `gsap`, `animejs`, `css-animations`, or `waapi` based on the project stack.\n- 3D/WebGL: use `three` if available.\n- Screenshot-to-code: use `image-to-code` or `yueban-image-to-code` if available.\n- Generated UI assets: use image generation skills only when the user asks for visual assets or the design requires them.\n\nIf no helper is available, continue with native framework/CSS and state the fallback briefly.\n\n### 5. Explore, present, and confirm the direction\n\nFor Level 2, present one recommended direction and up to two materially different alternatives when real alternatives exist. Use the lowest-cost artifact that answers the unresolved question: a layout outline, wireframe, standalone HTML prototype, screenshot or reference board, generated image, or motion prototype.\n\nPresent every review artifact before applying the confirmation gate. Resolve `scripts/present-design.py` relative to the loaded skill directory and pass all HTML directions in one invocation. On a shared local desktop, use `open` for standalone HTML; use the managed `serve` command only when HTTP is required. In remote, container, SSH, or headless environments, never present agent-side `127.0.0.1` or `file://` URLs as user-accessible; use host-exposed links or attached screenshots. Read `references/artifact-presentation.md` for lifecycle and fallback rules.\n\nWhen a confirmation gate applies:\n\n1. Verify that the user has an immediately usable way to inspect each artifact.\n2. Show the choices and give a recommendation.\n3. Ask the user to approve, choose, or propose changes.\n4. Stop implementation while the decision is pending.\n5. Restate the approved design contract before continuing.\n\nDo not create a review artifact and then continue coding past it in the same turn. Skip the pause for Level 0, clearly directed Level 1 work, or when the user explicitly grants autonomous design authority.\n\n### 6. Declare the design system\n\nBefore implementation, write:\n\n- Product role: operational tool, dashboard, editor, landing page, content site, prototype, etc.\n- Audience and use frequency.\n- Reference anchors: real apps, brands, design systems, or local existing UI.\n- Color system: neutral base, one accent, semantic colors.\n- Typography: display/body/code fonts or existing project font.\n- Spacing: base unit and container width.\n- Radius: one radius strategy.\n- Elevation: border, shadow, or flat hierarchy.\n- Motion: duration, easing, interaction triggers, reduced-motion behavior.\n- Anti-defaults: what must be avoided for this project.\n\nFor operational tools, admin panels, creator dashboards, and editors, prefer dense but calm working screens over marketing heroes, decorative cards, and large empty sections.\n\nFor approved Level 2 work, include the chosen page structure, responsive behavior, critical states, accepted tradeoffs, and rejected directions in the design contract. If review artifacts used provisional visual tokens, replace them with the approved system.\n\nFor approved Level 2 work or any substantial multi-state, multi-route implementation, read `references/implementation-contract.md`, create `.codex/design-guide/design-contract.json`, and validate it with `scripts/design-contract.py validate --require-approved` before coding. Do not mark a contract approved without user-reviewed artifact evidence.\n\n### 7. Build the approved v0\n\nFor new screens or major redesigns, implement a v0 with:\n\n- Real page layout and navigation.\n- Representative content, not lorem ipsum.\n- Main visual hierarchy and responsive structure.\n- Key empty/loading/error states if they affect layout.\n- Placeholder assets only when real assets are unavailable.\n\nTreat an approved HTML prototype as the v0 when it uses the target stack and is suitable to continue. Otherwise, build the v0 from the approved design contract. Stop after v0 only when the user requested an additional implementation checkpoint.\n\n### 8. Full implementation\n\nFollow the existing stack and code style first. Check `package.json` before importing libraries. Read only the matching section of `references/framework-adapters.md`. Do not add a new UI library unless the project lacks one and the dependency is justified.\n\nImplementation rules:\n\n- Use existing components, tokens, helpers, and routing conventions.\n- Avoid nested cards and section-as-card page structure.\n- Use icons from the existing icon family; do not hand-roll SVG icons.\n- Implement hover, focus, disabled, loading, empty, error, and long-text states where relevant.\n- Preserve semantic HTML, accessible names, complete keyboard behavior, focus management, contrast, zoom/reflow, reduced motion, and status/error announcements.\n- Keep text inside buttons and fixed UI elements stable across breakpoints.\n- Use CSS Grid for page structure when flex width math would be fragile.\n- Do not use viewport-scaled font sizes.\n- Avoid default AI-purple/blue gradients unless brand-justified.\n- Do not make a landing page when the user asked for a product, app, dashboard, tool, or editor; make the usable screen first.\n\n### 9. Run and Present the Implementation\n\nUse the project's existing development command. When a managed background preview is useful, start it with:\n\n```bash\npython3 scripts/run-preview.py start \\\n --command \"npm run dev -- --host 127.0.0.1\" \\\n --url http://127.0.0.1:3000\n```\n\nUse `status` and `stop` on the same script. On a shared desktop, allow it to open the browser automatically. In remote/headless environments, provide only a host-exposed URL or attached screenshots; do not claim that agent-side loopback is user-accessible.\n\n### 10. Production QA\n\nAfter implementation, read `references/quality-gates.md`. For substantial work, encode critical flows, states, breakpoints, accessibility requirements, performance budgets, and visual baselines in the approved contract, then run:\n\n```bash\npython3 scripts/verify-ui.py http://127.0.0.1:3000 \\\n --contract .codex/design-guide/design-contract.json \\\n --project-root .\n```\n\nAt minimum capture and inspect:\n\n- Desktop: `1440x900`\n- Tablet: `1024x768`\n- Mobile: `390x844`\n\nUse `scripts/capture-audit.py` when helpful:\n\n```bash\npython3 scripts/capture-audit.py http://localhost:3000 --out .codex/frontend-audit\n```\n\nInspect screenshots and generated diffs before final. Check text overflow, overlapping UI, broken spacing, unreadable contrast, mobile navigation, blank canvases, critical state coverage, and whether the page still matches the approved contract.\n\nIf reviewing a built artifact, read `references/review-rubric.md`.\n\n### 11. No-Ship Gates\n\nDo not claim completion when any required gate fails:\n\n- The app/page cannot be opened locally.\n- No screenshot or visual inspection was performed for a substantial visual change.\n- Mobile layout has obvious overflow, overlap, or unusable navigation.\n- Text is clipped inside buttons, cards, tabs, or fixed-size controls.\n- The result ignores the declared design read.\n- A review artifact was generated but not opened, attached, or exposed through a usable absolute link or URL.\n- Only a relative artifact path was provided for a confirmation gate.\n- A required confirmation gate was skipped or is still pending.\n- The implementation materially diverges from the approved design contract without resolving the change.\n- Typecheck/build/lint fails and the failure is related to the change.\n- A declared interaction, state, accessibility, visual regression, console-error, or performance gate fails.\n- Strict production verification was weakened with `--allow-missing-tools`.\n- The page looks like a generic AI SaaS template after logo/text substitution.\n\nFor substantial UI work, self-score before final:\n\n```text\nDirection fit: 0-10\nTask flow: 0-10\nVisual hierarchy: 0-10\nCraft: 0-10\nUsability: 0-10\nResponsiveness: 0-10\nOriginality: 0-10\n```\n\nIf any score is below 8, revise before delivery or clearly report why it cannot be fixed in this pass.\n\n### 12. Final response\n\nReport:\n\n- What changed.\n- Design depth, review artifacts, presentation method, and approval outcome when a confirmation gate applied.\n- Where to open it.\n- Screenshot/device checks performed.\n- Interaction, accessibility, visual, performance, build, lint, typecheck, and test checks actually run.\n- Remaining risks if anything could not be verified.\n\nKeep the response concise.\n\n## Quality Bar\n\nThe result should look like it belongs to this exact product and audience. If it could be pasted into any AI SaaS template with only the logo changed, revise before delivering.\n\nFile v0.1.2:README.md\n\n

\n \n \n \n \"design-guide\n \n

\n\n# design-guide\n\nEnglish | [简体中文](README.zh-CN.md)\n\n[![Validate](https://github.com/GrubbyLee/design-guide/actions/workflows/validate.yml/badge.svg)](https://github.com/GrubbyLee/design-guide/actions/workflows/validate.yml)\n[![Sync to Gitee](https://github.com/GrubbyLee/design-guide/actions/workflows/sync-to-gitee.yml/badge.svg)](https://github.com/GrubbyLee/design-guide/actions/workflows/sync-to-gitee.yml)\n[![Release](https://img.shields.io/github/v/release/GrubbyLee/design-guide)](https://github.com/GrubbyLee/design-guide/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n> A frontend design orchestration skill for Codex, Claude Code, Cursor, Qwen Code, and other AI development environments.\n\n`design-guide` is not another UI style preset. It is a frontend design and production engineering control skill: it helps an AI coding agent understand a repository, choose and present a design direction, lock an executable contract, implement the UI, and verify behavior and quality before delivery.\n\nCurrent version: **v0.1.1**. See [AIDE compatibility](COMPATIBILITY.md) for separate installed, synchronized, and provider-invoked evidence. Chinese release notes are available in [中文兼容性](COMPATIBILITY.zh-CN.md).\n\nUse it when you want fewer generic AI-looking interfaces and a more disciplined frontend design/development loop.\n\n## What It Does\n\n- Acts as a frontend entry skill and navigator.\n- Supports two modes:\n - **Navigation mode**: invoked without a concrete task, it lists the best frontend tasks and helper skills available in the environment.\n - **Execution mode**: invoked with a real task, it follows a structured design-to-implementation workflow.\n- Scales the design process from direct fixes to exploratory design, based on uncertainty and the cost of reversing a decision.\n- Produces and presents reviewable artifacts such as wireframes, standalone HTML prototypes, reference boards, images, or motion studies when they are needed.\n- Automatically opens standalone HTML on a shared local desktop, manages HTTP review servers when needed, and uses host-accessible links or screenshots in remote environments.\n- Pauses at explicit confirmation gates so the user can approve, choose a direction, or request changes before expensive implementation.\n- Routes tasks such as dashboards, admin panels, landing pages, redesigns, screenshot-to-code work, mobile UI, animation, 3D, and UI reviews.\n- Evaluates existing product/page designs by mode, scores strengths and weaknesses, flags generic AI-design tells, and outputs prioritized, actionable improvement plans with evidence, tradeoffs, acceptance criteria, and verification steps.\n- Inventories frameworks, routes, components, tokens, data contracts, test tools, and project risks before substantial implementation.\n- Turns approved designs into machine-validated contracts covering flows, states, breakpoints, accessibility, performance budgets, data schemas, visual baselines, and approval evidence.\n- Verifies declared interactions at responsive breakpoints with Playwright, console and overflow checks, axe accessibility audits, screenshot comparison, browser metrics, and optional Lighthouse gates.\n- Provides state/data guidance and adapters for React/Next/Remix, Vue/Nuxt, SvelteKit, Angular, static HTML, and embedded mobile web.\n- Starts real development servers as managed previews with health checks, browser opening, logs, status, and safe cleanup.\n- Uses project/local preference files without hard-coding personal taste into the public skill.\n- Provides deterministic scripts for project inspection, artifact presentation, contract validation, application previews, interaction QA, visual diffs, screenshot capture, and cross-AIDE syncing.\n- Ships behavior regression fixtures, three product-journey acceptance checks, specialized operational-UI review templates, and digest-based cross-AIDE version diagnosis.\n\n## Quick Start\n\nInstall for Codex:\n\n```bash\ngit clone https://github.com/GrubbyLee/design-guide.git ~/.codex/skills/design-guide\n```\n\nSynchronize the same skill across Codex, Claude Code, Cursor, and Qwen Code local skill directories:\n\n```bash\nbash ~/.codex/skills/design-guide/scripts/sync-aide.sh\npython3 ~/.codex/skills/design-guide/scripts/design-guide-doctor.py --strict\n```\n\nThe target `design-guide` directories are managed mirrors: stale files are removed, while `.git`, `.codex`, generated Python caches, and private `.design-guide/profile.md` files are excluded.\n\nThe sync script copies the current `design-guide` folder to these managed targets. When the source already equals a target, that target is skipped.\n\n```text\n~/.codex/skills/design-guide\n~/.claude/skills/design-guide\n~/.cursor/skills/design-guide\n~/.qwen/skills/design-guide\n```\n\n## Invocation\n\nDifferent AIDE tools use different skill invocation syntax. The portable contract is simple: ask the agent to use `design-guide`.\n\n| Environment | Suggested invocation |\n|---|---|\n| Codex | `use design-guide`, `design-guide`, `$design-guide`, or `@design-guide` when supported |\n| Claude Code | `/design-guide` when installed as a Claude skill, or `use design-guide` |\n| Cursor | `use design-guide`, or point the agent at `SKILL.md` |\n| Qwen Code | `use design-guide`, or point the agent at `SKILL.md` |\n| Other AIDE | Tell the agent to read `SKILL.md` and follow `design-guide` |\n\n## Mode 1: Navigation\n\nWhen you only type:\n\n```text\ndesign-guide\n```\n\nthe agent should not start coding. It should show a compact menu of frontend capabilities and helper skills, for example:\n\n```text\ndesign-guide is ready. Pick a frontend task:\n\n1. Build a product screen / dashboard / tool\n Primary: design-guide\n Helpers if available: web-design-engineer, webapp-testing\n\n2. Improve visual taste of an existing page\n Primary: design-guide\n Helpers if available: design-taste-frontend, web-design-guidelines\n\n3. Evaluate an existing product/page design\n Primary: design-guide\n Helpers if available: web-design-guidelines, webapp-testing, design-taste-frontend\n\n4. Add complex animation\n Primary: design-guide\n Helpers if available: gsap, animejs\n\n5. Build 3D / WebGL\n Primary: design-guide\n Helpers if available: three\n```\n\n## Mode 2: Execution\n\nWhen you provide a real task:\n\n```text\nUse design-guide to build a creator dashboard for reviewing generated media.\n```\n\nYou can also ask for a product design review:\n\n```text\nUse design-guide to evaluate this existing dashboard design and provide a prioritized improvement report.\nInput: \nOutput: scorecard, strengths, issues, actionable changes, acceptance criteria.\n```\n\nThe review workflow separates marketing pages, product workbenches, data dashboards, forms, mobile surfaces, redesign audits, accessibility audits, and competitive comparisons so dense product UI is not judged with landing-page rules.\n\nSpecialized templates add deeper evidence and acceptance criteria for data tables, dashboards, complex forms, mobile navigation, and high-risk batch actions. Mobile templates are loaded only when mobile is explicitly in scope or the artifact is mobile-first.\n\nThe agent should follow this loop:\n\n1. Inventory the project and read product context.\n2. Choose Level 0, 1, or 2 design depth.\n3. Define the user's job, information priority, structure, states, data, and success criteria.\n4. Select the smallest useful helper capability set.\n5. For exploratory work, produce the lowest-cost useful review artifact, present it, and wait for user confirmation.\n6. Record the approved design system and executable implementation contract.\n7. Build a viewable v0 for substantial work.\n8. Implement using the detected framework and repository conventions.\n9. Start and present a managed application preview when useful.\n10. Run interaction, state, accessibility, responsive, visual, console, and performance QA.\n11. Run the repository's build, lint, typecheck, and tests.\n12. Enforce no-ship gates before claiming completion.\n\nConfirmation is proportional, not automatic. Isolated fixes and clearly directed work can continue without interruption. New products, major redesigns, workflow changes, brand-defining pages, or artifacts explicitly presented for review require approval before full implementation. Creating a file is not presentation: the user must receive an opened browser view, attached media, or an immediately usable absolute link or URL.\n\n## Preference Files\n\n`design-guide` keeps open-source defaults separate from personal or project preferences.\n\nLookup order:\n\n```text\n1. .design-guide/profile.md in the current project\n2. ~/.design-guide/preferences.md on the local machine\n3. references/design-defaults.md bundled with this skill\n```\n\nTemplates:\n\n```text\nreferences/project-profile.example.md\nreferences/local-overrides.example.md\n```\n\nDo not commit private names, paths, API keys, or personal taste to the public skill.\n\n## Scripts\n\nGenerate structured project intelligence:\n\n```bash\npython3 scripts/inspect-project.py . --format markdown\n```\n\nCreate and validate an executable design contract:\n\n```bash\npython3 scripts/design-contract.py init --out .codex/design-guide/design-contract.json\npython3 scripts/design-contract.py validate .codex/design-guide/design-contract.json --project-root . --require-approved\n```\n\nStart, inspect, and stop a real application preview:\n\n```bash\npython3 scripts/run-preview.py start --command \"npm run dev\" --url http://127.0.0.1:3000\npython3 scripts/run-preview.py status\npython3 scripts/run-preview.py stop\n```\n\nRun contract-driven browser QA:\n\n```bash\npython3 scripts/verify-ui.py http://127.0.0.1:3000 \\\n --contract .codex/design-guide/design-contract.json --project-root .\n```\n\nCompare a screenshot against a visual baseline:\n\n```bash\npython3 scripts/visual-diff.py baseline.png current.png --diff-out diff.png\n```\n\nRun lightweight frontend environment detection:\n\n```bash\nbash scripts/detect-frontend-env.sh .\n```\n\nCapture desktop/tablet/mobile screenshots:\n\n```bash\npython3 scripts/capture-audit.py http://localhost:3000 --out .codex/frontend-audit\n```\n\nOpen one or more standalone HTML review artifacts and return immediately:\n\n```bash\npython3 scripts/present-design.py open \\\n \".codex/design//direction-a.html\" \\\n \".codex/design//direction-b.html\"\n```\n\nStart, inspect, and stop a managed background server when HTTP is required:\n\n```bash\npython3 scripts/present-design.py serve \".codex/design//prototype.html\"\npython3 scripts/present-design.py status\npython3 scripts/present-design.py stop\n```\n\nSync local AIDE copies:\n\n```bash\nbash scripts/sync-aide.sh\n```\n\nCheck versions and public-file digests across all supported AIDEs:\n\n```bash\npython3 scripts/design-guide-doctor.py --strict\n```\n\nRun an explicit provider-backed invocation smoke test (may consume model quota):\n\n```bash\npython3 scripts/smoke-aides.py --aide codex --yes-consume-provider-quota\n```\n\nRun the deterministic design-approval, review-isolation, and cross-AIDE product journeys:\n\n```bash\npython3 scripts/verify-product-journeys.py\n```\n\nSelect CLI language explicitly or through `F_DESIGN_LOCALE`:\n\n```bash\npython3 scripts/present-design.py --locale zh-CN --help\nF_DESIGN_LOCALE=zh-CN python3 scripts/design-guide-doctor.py\n```\n\nEvaluate a captured agent review against a scope contract:\n\n```bash\npython3 scripts/evaluate-review-output.py \\\n tests/fixtures/review-behavior/image-review-isolated.json \\\n response.md\n```\n\n## Repository Layout\n\n```text\n.\n├── SKILL.md\n├── SKILL.zh-CN.md\n├── VERSION\n├── design-guide.json\n├── CHANGELOG.md\n├── CHANGELOG.zh-CN.md\n├── COMPATIBILITY.md\n├── COMPATIBILITY.zh-CN.md\n├── RELEASE_NOTES.md\n├── RELEASE_NOTES.zh-CN.md\n├── UPGRADING.md\n├── UPGRADING.zh-CN.md\n├── agents/\n│ └── openai.yaml\n├── references/\n│ ├── aide-integration.md\n│ ├── internationalization.md\n│ ├── internationalization.zh-CN.md\n│ ├── anti-ai-design-tells.md\n│ ├── artifact-presentation.md\n│ ├── design-contract.schema.json\n│ ├── design-defaults.md\n│ ├── design-process.md\n│ ├── framework-adapters.md\n│ ├── helper-registry.md\n│ ├── implementation-contract.md\n│ ├── local-overrides.example.md\n│ ├── project-intelligence.md\n│ ├── project-profile.example.md\n│ ├── product-design-review.md\n│ ├── end-to-end-journeys.md\n│ ├── review-templates/\n│ ├── quality-gates.md\n│ ├── state-and-data.md\n│ └── review-rubric.md\n├── scripts/\n│ ├── i18n.py\n│ ├── capture-audit.py\n│ ├── design-contract.py\n│ ├── check-secrets.py\n│ ├── evaluate-review-output.py\n│ ├── design-guide-doctor.py\n│ ├── detect-frontend-env.sh\n│ ├── present-design.py\n│ ├── inspect-project.py\n│ ├── run-preview.py\n│ ├── smoke-aides.py\n│ ├── sync-aide.sh\n│ ├── verify-ui.py\n│ ├── verify-product-journeys.py\n│ └── visual-diff.py\n├── locales/\n│ ├── en.json\n│ └── zh-CN.json\n└── tests/\n ├── fixtures/quality/\n ├── fixtures/review-behavior/\n ├── test_behavior_evaluations.py\n ├── test_documentation_contract.py\n ├── test_i18n.py\n ├── test_present_design.py\n ├── test_quality_pipeline.py\n ├── test_release_tooling.py\n └── test_support_scripts.py\n```\n\n## Validation\n\nLocal checks:\n\n```bash\nbash -n scripts/*.sh\npython3 -m py_compile scripts/*.py\npython3 scripts/present-design.py --help >/dev/null\npython3 scripts/capture-audit.py --help >/dev/null\npython3 scripts/design-contract.py validate tests/fixtures/quality/design-contract.json --project-root . --require-approved\npython3 -m unittest discover -s tests -v\npython3 scripts/verify-product-journeys.py\npython3 scripts/check-secrets.py .\nbash scripts/detect-frontend-env.sh .\n```\n\nThe GitHub `validate.yml` workflow also runs a strict browser-quality job against the fixture contract with Playwright Chromium, axe-core, responsive state/keyboard flows, screenshots, and Lighthouse. Verification reports and screenshots are uploaded as workflow artifacts.\n\n## Versioning And Releases\n\nThe current release is declared in `VERSION` and `design-guide.json`. See `CHANGELOG.md` ([中文](CHANGELOG.zh-CN.md)) for changes, `RELEASE_NOTES.md` ([中文](RELEASE_NOTES.zh-CN.md)) for the current release summary, and `UPGRADING.md` ([中文](UPGRADING.zh-CN.md)) for safe upgrade instructions. Provider-side AIDE invocation remains an explicit, separately reported check because it can consume external model quota.\n\n## Gitee Mirror\n\nThis repository is configured to sync `main` and tags to:\n\n```text\nhttps://gitee.com/synovation/design-guide\n```\n\nThe mirror workflow expects these GitHub repository secrets:\n\n```text\nGITEE_USERNAME\nGITEE_TOKEN\n```\n\n`GITEE_TOKEN` should have repository/project write permission.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nFile v0.1.2:_meta.json\n\n{\n \"ownerId\": \"kn7fzmvcq3sggwf0kjtbz67mwx8bqeq9\",\n \"slug\": \"f-design-2\",\n \"version\": \"0.1.2\",\n \"publishedAt\": 1786205413728\n}\n\nFile v0.1.2:references/aide-integration.md\n\n# AIDE Integration\n\nUse this reference only when the user asks how to install, sync, or invoke `design-guide` across AI development environments.\n\n## Local Source of Truth\n\nPrimary folder:\n\n```text\n~/.codex/skills/design-guide\n```\n\nUse the current repository as the source of truth. A conventional Codex installation uses the folder above; the sync script safely skips it when source and target are identical.\n\n## Known Local Targets\n\nSupported local skill roots:\n\n```text\n~/.codex/skills\n~/.claude/skills\n~/.cursor/skills\n~/.qwen/skills\n```\n\nRecommended install paths:\n\n```text\n~/.codex/skills/design-guide\n~/.claude/skills/design-guide\n~/.cursor/skills/design-guide\n~/.qwen/skills/design-guide\n```\n\n## Invocation Guide\n\n- Codex: \"use design-guide\", `design-guide`, `$design-guide`, or `@design-guide` if the interface supports it.\n- Claude Code: `/design-guide` when installed as a Claude skill; otherwise say \"use design-guide\".\n- Cursor: say \"use design-guide\"; if it does not detect the skill, point it to the local `SKILL.md`.\n- Qwen Code: say \"use design-guide\"; if it does not detect the skill, point it to the local `SKILL.md`.\n- Unknown AIDE: add the folder to the tool's skill/rule/context directory, or paste the `SKILL.md` path and ask the agent to follow it.\n\n## Sync\n\nRun:\n\n```bash\nbash ~/.codex/skills/design-guide/scripts/sync-aide.sh\n```\n\nThe script copies the source folder into Codex, Claude, Cursor, and Qwen skill directories. It skips any target that resolves to the source itself.\n\nEach target is a managed mirror. Files that no longer exist in the source are removed. Repository metadata, temporary review artifacts, generated Python caches, and `.design-guide/profile.md` are excluded.\n\nFor an isolated verification or managed environment, redirect only the target root:\n\n```bash\nF_DESIGN_TARGET_HOME=/path/to/sandbox \\\n bash ~/.codex/skills/design-guide/scripts/sync-aide.sh\n```\n\nThe source can be overridden independently with `F_DESIGN_SRC`.\n\nThe sync command ends with a strict doctor check. A successful copy is not reported as synchronized until every public-file digest matches the source.\n\n## Version And Upgrade Diagnosis\n\nCheck the repository version and every local AIDE mirror:\n\n```bash\npython3 scripts/design-guide-doctor.py --strict\n```\n\nMachine-readable output:\n\n```bash\npython3 scripts/design-guide-doctor.py --strict --json\n```\n\nUpgrade a Git clone source, verify it, and synchronize the local mirrors:\n\n```bash\ngit -C ~/.codex/skills/design-guide pull --ff-only\npython3 ~/.codex/skills/design-guide/scripts/design-guide-doctor.py\nbash ~/.codex/skills/design-guide/scripts/sync-aide.sh\n```\n\nIf the active source is another checkout, set `F_DESIGN_SRC` explicitly before syncing. Restart or reload each AIDE after an upgrade when it caches skill discovery.\n\n## Compatibility Verification\n\nUse three levels of evidence and report them separately:\n\n1. **Installed:** the AIDE CLI and its `design-guide/SKILL.md` path exist.\n2. **Synchronized:** the installed copy matches the source after documented exclusions.\n3. **Invoked:** the AIDE is asked to use `design-guide` and demonstrates navigation or execution behavior in a real session.\n\nDo not report version checks or file synchronization as successful invocation. Real invocation may contact an external model provider, so run it only when that external request is authorized.\n\n## Project And Local Preferences\n\nPortable default rules live in the skill folder. Personal preferences should stay outside the public skill source:\n\n```text\n.design-guide/profile.md\n~/.design-guide/preferences.md\n```\n\nUse these templates when needed:\n\n```text\nreferences/project-profile.example.md\nreferences/local-overrides.example.md\n```\n\nDo not hard-code private names, brands, directories, API keys, or personal taste into `SKILL.md` before publishing.\n\n## Compatibility Principle\n\nDo not rely on one product's invocation syntax inside the skill body. The portable contract is:\n\n```text\nRead SKILL.md and follow design-guide.\n```\n\n## CLI Language\n\nThe AIDE invocation syntax and the helper CLI locale are independent. Use `--locale zh-CN` for a single command or set `F_DESIGN_LOCALE=zh-CN` for the session. See `references/internationalization.md` for precedence, fallback, and JSON stability rules.\n\nFile v0.1.2:references/anti-ai-design-tells.md\n\n# Anti-AI Design Tell Review\n\nUse this as a companion to `references/product-design-review.md` and `references/review-rubric.md` when the user asks for design critique, redesign readiness, visual polish, or says the interface looks generic, templated, or AI-generated.\n\nThis file is not a style preference list. Treat each item as a diagnostic signal. A pattern is only a finding when it harms product fit, task clarity, trust, originality, accessibility, or conversion.\n\n## High-Confidence Tells\n\nFlag these with evidence when visible:\n\n- Default AI purple/blue gradients, neon glows, or decorative mesh backgrounds with no brand rationale.\n- Three equal feature cards or repeated equal cards where the content has different importance.\n- Centered hero with vague headline, vague subtext, and generic CTA.\n- Fake dashboard, fake terminal, or fake product preview built from decorative rectangles instead of a real screenshot, generated asset, or actual component.\n- Fake-precise metrics such as `99.9%`, `10x`, `48k`, or `92%` without source, label, or sample context.\n- Decorative status dots, version labels, build metadata, or weather/time/location strips that do not convey real state.\n- Overused eyebrow labels on every section, especially numbered labels such as `01`, `002`, `INDEX`, or `PHASE`.\n- Mixed visual systems: inconsistent radius, icon families, shadows, typography, button styles, or neutral palettes.\n- Card nesting and section-as-card structure that hides hierarchy instead of clarifying it.\n- Generic names, generic avatars, placeholder companies, or `Acme`-style brands presented as real content.\n- Copy that reads like filler: \"seamless\", \"elevate\", \"unlock\", \"next-gen\", \"effortless\", or poetic phrases that do not explain the product.\n\n## Product UI Tells\n\nFor dashboards, admin panels, tools, editors, and workbenches, also check:\n\n- Marketing-page hero structure used for an operational tool.\n- Excessive empty space that slows scanning in high-frequency work.\n- Metrics shown as decorative cards without drilldown, source, freshness, or action path.\n- Tables hidden behind card grids when users need comparison, sorting, filtering, or bulk action.\n- Every row action exposed equally instead of prioritizing common actions and protecting dangerous actions.\n- Bulk actions without impact summary, permission gating, confirmation, undo, or audit trail.\n- Empty/loading/error states omitted because only the successful demo state was designed.\n- High-risk AI outputs shown with opaque scores instead of explainable reasons and evidence.\n- Mobile layout merely squeezed from desktop, with fixed toolbars, clipped labels, or unreachable primary actions.\n\n## Marketing And Conversion Tells\n\nFor landing pages, homepages, pricing pages, and campaign pages, also check:\n\n- Hero value proposition could apply to any SaaS after changing the logo.\n- CTA labels change wording across nav, hero, pricing, and footer for the same intent.\n- Trust logos are plain text wordmarks or invented customer names presented as credibility.\n- Screenshots are fake product UI and do not show a believable workflow.\n- Each section repeats the same layout family.\n- Long feature lists are used instead of grouping, proof, demos, or task-based narratives.\n- Testimonials are too long, unattributed, or generic.\n\n## Recommendation Rule\n\nWhen flagging an AI tell, do not stop at criticism. Convert it into an implementable change:\n\n```text\nFinding: \nEvidence: \nImpact: \nRecommendation: \nAcceptance criteria: \n```\n\n## Do Not Overapply\n\n- Do not penalize a simple design just because it is simple.\n- Do not penalize density in an operational cockpit when density supports expert work.\n- Do not force unusual visual patterns when a regulated, enterprise, or public-sector product needs predictability.\n- Do not require image generation for internal tools unless visuals are part of the reviewed experience.\n- Do not copy taste-skill landing-page bans blindly into dashboards, data tables, editors, or workflow-heavy product UI.\n\nFile v0.1.2:references/artifact-presentation.md\n\n# Artifact Presentation\n\nRead this whenever creating an artifact for user review. Creating a file is not presentation. Complete presentation only when the user has an immediately usable review surface.\n\n## Choose The Transport\n\nDetermine whether the agent and user share the same desktop and filesystem before opening anything.\n\n- **Shared local desktop:** Automatically open standalone HTML and return immediately.\n- **Shared desktop, HTTP required:** Start the managed background server, then open its URL.\n- **Remote, container, SSH, or headless:** Do not present agent-side `127.0.0.1` or `file://` URLs as user-accessible. Use a host-provided forwarded URL, attach rendered screenshots, or provide an artifact link exposed by the AIDE.\n- **Unknown environment:** Treat it as remote until access is demonstrated.\n\nRequest tool approval when opening a browser requires it. Do not silently skip the attempt merely because the host may prompt. Do not automatically open imported or otherwise untrusted HTML; render it in an isolated browser or use screenshots.\n\n## Open Standalone HTML\n\nResolve the script path relative to the loaded `design-guide` skill directory. Pass every direction in one invocation:\n\n```bash\npython3 /scripts/present-design.py open \\\n \".codex/design//direction-a.html\" \\\n \".codex/design//direction-b.html\"\n```\n\nThe command opens each artifact in a browser tab and exits. It always prints absolute paths and file URLs as diagnostics. Browser-open success means only that the request was accepted; still ask the user to inspect and confirm.\n\n## Serve HTTP Artifacts\n\nUse HTTP only when modules, fetch calls, routing, or browser security rules prevent `file://` operation. The command starts a managed background process and returns:\n\n```bash\npython3 /scripts/present-design.py serve \\\n \".codex/design//direction-a.html\" \\\n \".codex/design//direction-b.html\"\n```\n\nManage the server from the project root:\n\n```bash\npython3 /scripts/present-design.py status\npython3 /scripts/present-design.py stop\n```\n\nThe server binds only to loopback, records state under `.codex/design/presentation.json`, and serves multiple artifacts from one directory. Stop it after review unless the approved implementation still needs it. If the project already has a development server, open its host-accessible URL instead.\n\n## Present Other Artifacts\n\n- Attach images or screenshots when the host supports image output.\n- Show the rendered reference board or diagram instead of only its source file.\n- Provide playable motion output in a supported format.\n- Label every direction so artifacts map unambiguously to the direction descriptions.\n\n## Apply Fallbacks\n\nUse the first fallback that the user can actually access:\n\n1. A host-provided or forwarded HTTP URL.\n2. An AIDE artifact link or a clickable absolute path on a shared filesystem.\n3. Attached desktop and mobile screenshots.\n4. A concise explanation of the limitation and one exact manual opening action.\n\nNever provide only a relative path. Never treat an agent-local loopback URL as usable in a remote session. Never claim the user saw an artifact merely because an open command succeeded.\n\n## Verify Before Confirmation\n\nBefore asking for approval:\n\n- Confirm that the chosen review surface is accessible from the user's environment.\n- Inspect the rendered artifact at the required viewports.\n- Check local assets and primary interactions.\n- State what was opened or attached and retain an accessible fallback.\n- Keep the background server reachable until confirmation, then stop it.\n\nOnly then ask the user to approve, choose, or propose changes. If no usable presentation path exists, report the blocker instead of treating the confirmation gate as active.\n\nFile v0.1.2:references/design-contract.schema.json\n\n{\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"$id\": \"https://github.com/GrubbyLee/design-guide/references/design-contract.schema.json\",\n \"title\": \"design-guide implementation contract\",\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\n \"schemaVersion\",\n \"contractStatus\",\n \"productRole\",\n \"audience\",\n \"primaryFlow\",\n \"breakpoints\",\n \"requiredStates\",\n \"flows\",\n \"designSystem\",\n \"accessibility\",\n \"performance\",\n \"dataContracts\",\n \"approval\"\n ],\n \"properties\": {\n \"schemaVersion\": {\"const\": \"1.0\"},\n \"contractStatus\": {\"enum\": [\"draft\", \"approved\"]},\n \"productRole\": {\"type\": \"string\", \"minLength\": 1},\n \"audience\": {\"type\": \"string\", \"minLength\": 1},\n \"primaryFlow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\"type\": \"string\", \"minLength\": 1}\n },\n \"breakpoints\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\"type\": \"integer\", \"minimum\": 240}\n },\n \"requiredStates\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\"type\": \"string\", \"minLength\": 1}\n },\n \"flows\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"id\", \"coversStates\", \"start\", \"steps\"],\n \"properties\": {\n \"id\": {\"type\": \"string\", \"pattern\": \"^[a-z0-9][a-z0-9-]*$\"},\n \"coversStates\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\"type\": \"string\", \"minLength\": 1}\n },\n \"start\": {\"type\": \"string\", \"minLength\": 1},\n \"steps\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"action\"],\n \"properties\": {\n \"action\": {\n \"enum\": [\"goto\", \"click\", \"fill\", \"press\", \"expect-visible\", \"expect-hidden\", \"expect-text\", \"expect-url\", \"screenshot\"]\n },\n \"selector\": {\"type\": \"string\"},\n \"value\": {\"type\": \"string\"},\n \"name\": {\"type\": \"string\"},\n \"timeoutMs\": {\"type\": \"integer\", \"minimum\": 0}\n }\n }\n }\n }\n }\n },\n \"designSystem\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"color\", \"typography\", \"spacing\", \"radius\", \"motion\"],\n \"properties\": {\n \"color\": {\"type\": \"string\", \"minLength\": 1},\n \"typography\": {\"type\": \"string\", \"minLength\": 1},\n \"spacing\": {\"type\": \"string\", \"minLength\": 1},\n \"radius\": {\"type\": \"string\", \"minLength\": 1},\n \"motion\": {\"type\": \"string\", \"minLength\": 1}\n }\n },\n \"accessibility\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"maxAxeViolations\", \"keyboardComplete\", \"requireAccessibleNames\", \"reducedMotion\"],\n \"properties\": {\n \"maxAxeViolations\": {\"type\": \"integer\", \"minimum\": 0},\n \"keyboardComplete\": {\"type\": \"boolean\"},\n \"requireAccessibleNames\": {\"type\": \"boolean\"},\n \"reducedMotion\": {\"type\": \"boolean\"}\n }\n },\n \"performance\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"maxLoadMs\", \"maxTransferBytes\", \"maxRequests\", \"maxConsoleErrors\", \"maxVisualDiffRatio\", \"minLighthouseScore\"],\n \"properties\": {\n \"maxLoadMs\": {\"type\": \"number\", \"minimum\": 0},\n \"maxTransferBytes\": {\"type\": \"integer\", \"minimum\": 0},\n \"maxRequests\": {\"type\": \"integer\", \"minimum\": 0},\n \"maxConsoleErrors\": {\"type\": \"integer\", \"minimum\": 0},\n \"maxVisualDiffRatio\": {\"type\": \"number\", \"minimum\": 0, \"maximum\": 1},\n \"minLighthouseScore\": {\"type\": \"number\", \"minimum\": 0, \"maximum\": 1}\n }\n },\n \"dataContracts\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"path\", \"type\", \"required\"],\n \"properties\": {\n \"path\": {\"type\": \"string\", \"minLength\": 1},\n \"type\": {\"enum\": [\"openapi\", \"json-schema\", \"graphql\", \"typescript\"]},\n \"required\": {\"type\": \"boolean\"}\n }\n }\n },\n \"visualBaselines\": {\n \"type\": \"object\",\n \"additionalProperties\": {\"type\": \"string\", \"minLength\": 1}\n },\n \"approval\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"direction\", \"artifacts\", \"tradeoffs\"],\n \"properties\": {\n \"direction\": {\"type\": \"string\"},\n \"artifacts\": {\"type\": \"array\", \"items\": {\"type\": \"string\", \"minLength\": 1}},\n \"tradeoffs\": {\"type\": \"array\", \"items\": {\"type\": \"string\", \"minLength\": 1}}\n }\n }\n }\n}\n\nFile v0.1.2:references/design-defaults.md\n\n# Design Defaults\n\nUse these defaults when no project or local preference file overrides them.\n\n## Process Defaults\n\n- Match design depth to uncertainty and reversal cost.\n- Use a concise brief and layout/state outline for established products.\n- Produce a reviewable artifact and obtain confirmation for exploratory, workflow-changing, or brand-defining work.\n- Automatically open local HTML when the agent and user share a desktop; otherwise use a host-accessible link or attached screenshots, never an agent-local loopback URL.\n- Once an artifact is presented for approval, pause until the user approves, chooses, or requests changes.\n- Use the lowest-cost artifact that resolves the open question; do not create polished mockups by habit.\n\n## Product Defaults\n\n- Build the actual usable screen first for apps, dashboards, editors, and tools.\n- Prefer calm density for repeated work: clear hierarchy, compact controls, predictable navigation.\n- Use representative domain content. Avoid lorem ipsum unless the user explicitly asks for placeholders.\n- Preserve existing product conventions before introducing a new visual language.\n\n## Visual Defaults\n\n- Use one neutral base and one primary accent unless the brand requires more.\n- Avoid generic AI-purple/blue gradients as the default.\n- Avoid decorative nested cards, oversized hero sections, meaningless glow, and card grids that do not map to real information.\n- Keep radius strategy consistent: choose sharp, small, medium, or pill by role and follow it.\n- Use real images/assets for product, brand, venue, object, or portfolio work when available.\n\n## Interaction Defaults\n\n- Implement hover, focus, disabled, loading, empty, error, and long-text states where relevant.\n- Use icons from the existing icon family. Do not hand-roll SVG icons for common glyphs.\n- Use CSS Grid for stable page structure when flex width math would be fragile.\n- Keep fixed controls stable across breakpoints.\n\n## Responsive Defaults\n\n- Audit mobile widths for overflow and clipped controls.\n- Do not scale font size with viewport width.\n- Use stable dimensions for boards, tiles, toolbars, counters, and fixed-format controls.\n- Avoid `h-screen` for mobile full-height layouts; prefer dynamic viewport units when supported by the stack.\n\n## Verification Defaults\n\n- Run the existing build/typecheck/lint commands when relevant and affordable.\n- Capture desktop, tablet, and mobile screenshots for substantial visual changes.\n- Revise before delivery if screenshots reveal overlap, blank regions, illegible contrast, or broken hierarchy.\n\nFile v0.1.2:references/design-process.md\n\n# Design Process\n\nRead this reference for new screens, major redesigns, ambiguous visual direction, workflow changes, or any task where implementation would make the design expensive to reconsider.\n\n## Choose The Design Depth\n\nUse the lightest process that resolves the real uncertainty.\n\n- **Level 0 - Direct fix:** Use for isolated styling, copy, spacing, or component-state corrections. Preserve the existing design contract and implement directly.\n- **Level 1 - Directed design:** Use when the product structure and visual language already exist. Write a concise design brief and layout/state outline, then proceed unless the user requested review.\n- **Level 2 - Exploratory design:** Use for new products, new major screens, information-architecture changes, brand-defining pages, major redesigns, or competing plausible directions. Produce a reviewable artifact and obtain confirmation before full implementation.\n\nRaise the level when uncertainty or reversal cost is high. Do not lower it merely to avoid asking for a decision.\n\n## Produce The Design Brief\n\nDefine these items before choosing visual details:\n\n- Product role and target audience.\n- Primary job the user is trying to complete.\n- Most frequent or highest-value workflow.\n- Content and actions that deserve first, second, and third visual priority.\n- Required routes, regions, states, and breakpoints.\n- Existing brand, technical, accessibility, and content constraints.\n- Observable success criteria for the design.\n\nKeep the brief concise. Surface assumptions that would materially change the result.\n\n## Map Structure And Flow\n\nFor Level 1, provide a compact page outline and name the important states.\n\nFor Level 2, show the primary flow and information architecture before polishing visuals. Include entry, main action, completion, empty, loading, error, and recovery paths when relevant.\n\nUse a flow diagram only when it makes branching or state transitions easier to understand. Use a wireframe when region hierarchy or responsive behavior is the main question.\n\n## Explore Directions\n\nCreate alternatives only when they represent meaningful choices. Vary hierarchy, density, navigation, interaction model, editorial tone, or visual language; do not present cosmetic color swaps as separate directions.\n\nFor each direction, state:\n\n- The organizing idea.\n- The user or product benefit.\n- The main tradeoff.\n- The reference anchors.\n- Why it fits or conflicts with the design brief.\n\nRecommend one direction. Do not force the user to compare more than three.\n\n## Choose Review Artifacts\n\nCreate the lowest-cost artifact that can answer the open design question:\n\n- Use a written layout outline for a narrow, well-understood screen.\n- Use an ASCII or image wireframe for hierarchy and region placement.\n- Use a standalone HTML prototype for responsive layout, interaction, density, or navigation.\n- Use screenshots, a reference board, or a generated image for visual language, art direction, or asset-heavy pages.\n- Use a motion prototype or short capture when timing and choreography are central.\n\nUse representative domain content. Label placeholders and speculative assets. Do not present a polished mockup that hides unresolved workflow problems.\n\nStore temporary review artifacts under `.codex/design//` by default. If the project has an established design-artifact location, use it instead. Read `references/artifact-presentation.md`, make the artifact immediately inspectable, and give the user a usable fallback URL or absolute path.\n\n## Apply The Confirmation Gate\n\nRequire confirmation before full implementation when any of these is true:\n\n- The user requested a preview, options, or approval step.\n- The task is Level 2.\n- The design changes navigation, information architecture, or a primary workflow.\n- Two or more materially different directions remain credible.\n- Brand-defining visuals or expensive custom assets would be difficult to reverse.\n- A review artifact was presented specifically for user judgment.\n\nWhen the gate applies:\n\n1. Present the artifact through an opened browser, attached media, or another immediately usable review surface.\n2. Ask the user to approve, choose an option, or describe changes.\n3. Stop implementation while that decision is pending.\n4. Incorporate the response and restate the approved design contract before continuing.\n\nDo not create artificial pauses for Level 0 work, a precisely specified screenshot recreation, an existing locked design system, or work where the user explicitly authorizes autonomous design decisions. If a supposedly locked direction conflicts with the product goal or accessibility, surface the issue instead of silently following it.\n\n## Lock The Design Contract\n\nAfter approval, record the decisions that implementation must preserve:\n\n- Page structure and primary workflow.\n- Chosen direction and reference anchors.\n- Color, typography, spacing, radius, elevation, icon, and motion rules.\n- Responsive behavior and important states.\n- Accepted tradeoffs and rejected alternatives.\n\nTreat later implementation discoveries as design changes when they alter this contract. Return to the user only when the change is material; resolve small execution details autonomously.\n\nFile v0.1.2:references/end-to-end-journeys.md\n\n# End-To-End Product Journeys\n\nThese journeys are the minimum release-level acceptance suite for `design-guide`. They validate product behavior across design approval, existing-product improvement, and local AIDE distribution. Run them with:\n\n```bash\npython3 scripts/verify-product-journeys.py\n```\n\n## Journey 1: New Product From Direction To Verified Build\n\nUser goal:\n\n```text\nUse design-guide to design and build a stateful product workbench.\n```\n\nRequired evidence:\n\n1. The task is classified as Level 2.\n2. A reviewable artifact is created and presented through an immediately usable method.\n3. Implementation pauses until the user confirms a direction.\n4. The approved contract cites the artifact and records the approval decision.\n5. The implementation covers representative states and required breakpoints.\n6. Strict browser verification passes without `--allow-missing-tools`.\n\nAutomated fixtures:\n\n- `tests/fixtures/quality/review-artifact.html`\n- `tests/fixtures/quality/design-contract.json`\n- `tests/fixtures/quality/index.html`\n- `.github/workflows/validate.yml` job `browser-quality`\n\n## Journey 2: Existing Page Review To Measurable Improvement\n\nUser goal:\n\n```text\nEvaluate an existing desktop page and propose practical improvements.\n```\n\nRequired evidence:\n\n1. The response starts with the explicit review scope and exclusions.\n2. Unrelated historical goals are not inherited.\n3. Findings cite observable evidence and distinguish strengths from P0/P1/P2 problems.\n4. Recommendations include implementation hints, tradeoffs, effort, acceptance criteria, and verification.\n5. If the user approves implementation, the normal design-depth and contract gates resume.\n6. A before/after comparison uses the same rubric and records improvements, regressions, and unresolved risks.\n\nAutomated fixtures:\n\n- `tests/fixtures/review-behavior/*.json`\n- `tests/fixtures/review-behavior/*.md`\n- `scripts/evaluate-review-output.py`\n\n## Journey 3: Install, Synchronize, And Invoke Across AIDEs\n\nUser goal:\n\n```text\nUse the same design-guide behavior in Codex, Claude Code, Cursor, and Qwen Code.\n```\n\nRequired evidence:\n\n1. `sync-aide.sh` copies the public skill into all four supported locations.\n2. Generated/private files and project preferences are excluded.\n3. The post-sync public digest matches the source in every target.\n4. `design-guide-doctor.py --strict` reports the same version and required files everywhere.\n5. “Installed”, “synchronized”, and “invoked” remain separate claims; real provider calls are optional and require authorization.\n\nAutomated fixtures:\n\n- `tests/test_support_scripts.py`\n- `tests/test_release_tooling.py`\n- `scripts/design-guide-doctor.py`\n\n## Release Gate\n\nA release is blocked when any journey loses its required fixture, documented acceptance criteria, or automated verification. A provider-side invocation failure may be reported separately when local installation and synchronization still pass.\n\nFile v0.1.2:references/framework-adapters.md\n\n# Framework Adapters\n\nRead only the section matching the detected stack. Preserve local conventions when they conflict with these generic defaults.\n\n## React, Next.js, and Remix\n\n- Respect server/client boundaries and existing route conventions.\n- Keep server data, URL state, remote cache state, and transient component state distinct.\n- Reuse the installed query, form, schema, and UI libraries.\n- Test user-visible behavior with Testing Library and route-critical flows with Playwright.\n- In Next.js, verify loading, error, not-found, metadata, image/font behavior, and hydration warnings.\n\n## Vue and Nuxt\n\n- Follow Composition API, composable, Pinia, and file-routing conventions already present.\n- Keep reactive derivations computed rather than mirrored through watchers.\n- In Nuxt, verify server rendering, hydration, route middleware, pending/error states, and asset handling.\n- Use Vue Testing Library or the repository's current component harness plus Playwright for critical flows.\n\n## Svelte and SvelteKit\n\n- Prefer local reactive state and existing stores; avoid adding a global store for route-local state.\n- Keep load/action contracts aligned with generated route types.\n- Verify SSR, form enhancement, invalidation, navigation focus, loading, and error boundaries.\n\n## Angular\n\n- Follow standalone/module, signals/RxJS, forms, routing, and dependency-injection conventions already selected by the project.\n- Preserve OnPush and immutable update assumptions where present.\n- Test semantic component behavior and router-integrated flows, not implementation internals.\n\n## Static HTML and Progressive Enhancement\n\n- Use semantic HTML as the primary contract and keep the core task usable without unnecessary JavaScript.\n- Use CSS custom properties for tokens and small modules for behavior.\n- Serve over HTTP when validating routes, modules, fetches, service workers, or strict browser security behavior.\n\n## Mobile Web and Embedded WebViews\n\n- Include safe areas, virtual keyboard behavior, touch targets, scroll ownership, orientation, back navigation, reduced resources, and host bridge failure states.\n- Test on a narrow viewport and, when available, the actual host shell. Browser emulation does not validate every WebView behavior.\n\n## Framework-Neutral Adapter Contract\n\nRegardless of stack, map the approved contract onto:\n\n```text\nroute -> page/screen owner\ndesign tokens -> theme source\ninteraction state -> local/form/state-machine owner\nremote data -> client/cache/server owner\ndata contract -> schema/generated types\nflows -> component/integration/browser tests\nvisual baselines -> stable fixture route\nquality commands -> package scripts and CI\n```\n\nFile v0.1.2:references/helper-registry.md\n\n# Helper Registry\n\nUse this registry to recommend or select helper skills/tools. Only name helpers that are visible in the current host environment; otherwise say they are not detected and continue with a fallback.\n\n## Build And Polish\n\n- `web-design-engineer`: build polished HTML/CSS/JS/React visual artifacts.\n- `design-taste-frontend`: correct generic AI-looking landing pages, portfolios, and redesigns.\n- `web-design-guidelines`: audit UI, UX, accessibility, and web-interface best practices.\n- `webapp-testing`: browser-based testing and screenshot QA when available.\n- Product design reviews use `design-guide` as the primary evaluator. Use `web-design-guidelines` for accessibility and UX critique, `webapp-testing` for screenshot/interaction evidence, and `design-taste-frontend` only for marketing-page, portfolio, or redesign taste signals that fit the artifact.\n\n## Motion\n\n- `css-animations`: simple CSS keyframes, transitions, and microinteractions.\n- `waapi`: Web Animations API for native timeline control.\n- `animejs`: lightweight JS animation where framework coupling is low.\n- `gsap`: complex sequencing, scroll-triggered motion, SVG motion, and heavier choreography.\n\n## 3D And Rich Media\n\n- `three`: 3D/WebGL scenes and interactive 3D experiences.\n- `lottie`: Lottie animation integration and asset handling.\n- `web-video-presentation`: browser-rendered video/presentation work.\n- `remotion-to-hyperframes`: Remotion migration or translation work when relevant.\n\n## Screenshot, Image, And Asset Work\n\n- `image-to-code`: turn screenshots into frontend code.\n- `yueban-image-to-code`: pixel-level screenshot-to-code when available.\n- `gpt-image-2`, `hoviw-image-gen`, `baoyu-image-gen`: generate image assets when the user asks for assets or the interface depends on them.\n- `image-enhancer`: improve existing raster assets.\n\n## Design Systems And Specialized UI\n\n- `aceternity-ui`: animated component ideas; do not let it decide the whole product style.\n- `minimalist-ui`: clean minimal UI direction when available.\n- `ui-ux-pro-max`: high-level UI/UX critique or design enhancement when available.\n- `weapp-tailwindcss`, `wechat-miniprogram-skill`, `miniprogram-development`: WeChat mini-program and related frontend work.\n\n## Selection Rule\n\nPrefer fewer helpers. Pick the smallest set that covers the task:\n\n- New app screen: `design-guide` plus local framework/CSS, optionally `web-design-engineer`.\n- Existing UI improvement: `design-guide` plus `design-taste-frontend` or `web-design-guidelines`.\n- Existing product/page design evaluation: `design-guide` plus `web-design-guidelines` for critique depth, `webapp-testing` for screenshot/interaction evidence, and `design-taste-frontend` only when landing-page or visual taste heuristics apply.\n- Animation: `design-guide` plus one motion helper.\n- 3D: `design-guide` plus `three`.\n- Screenshot recreation: `design-guide` plus one screenshot-to-code helper.","readmeExcerpt":"Skill: Design Guide Owner: grubbylee Summary: Frontend design, implementation, and production QA Tags: latest:0.1.2 Version history: v0.1.2 | 2026-08-08T16:10:13.728Z | auto - Initial release of f-design-2 v0.1.2 as \"design-guide\": a comprehensive frontend design and production engineering orchestrator. - Introduces structured reference routing for design, implementation, review, and environment-specific decisions. -","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"design-guide is ready. Pick a frontend task:\n\n1. Build a product screen / dashboard / tool\n Primary: design-guide\n Helpers if available: web-design-engineer, webapp-testing\n\n2. Improve visual taste of an existing page\n Primary: design-guide\n Helpers if available: design-taste-frontend, web-design-guidelines\n\n3. Evaluate an existing product/page design\n Primary: design-guide\n Helpers if available: web-design-guidelines, webapp-testing, design-taste-frontend\n\n4. Add complex animation\n Primary: design-guide\n Helpers if available: gsap, animejs\n\n5. Build 3D / WebGL\n Primary: design-guide\n Helpers if available: three"},{"language":"text","snippet":"Reading this as: for , with a language, leaning toward ."},{"language":"bash","snippet":"python3 scripts/inspect-project.py . --format markdown"},{"language":"bash","snippet":"python3 scripts/run-preview.py start \\\n --command \"npm run dev -- --host 127.0.0.1\" \\\n --url http://127.0.0.1:3000"},{"language":"bash","snippet":"python3 scripts/verify-ui.py http://127.0.0.1:3000 \\\n --contract .codex/design-guide/design-contract.json \\\n --project-root ."},{"language":"bash","snippet":"python3 scripts/capture-audit.py http://localhost:3000 --out .codex/frontend-audit"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: design-guide\ndescription: Frontend design and production engineering orchestrator that inventories projects, scales design depth, presents review artifacts, locks executable contracts, implements accessible responsive interfaces, and verifies interactions, visual regressions, and performance. Use when the user invokes design-guide, @design-guide, /design-guide, asks for frontend design/development/redesign, web app UI, dashboard, tool interface, landing page, responsive React/HTML/CSS work, design previews or choices, screenshot QA, production frontend quality, or says they are dissatisfied with generic AI-looking UI. If invoked without a concrete task, enter navigation mode and recommend the best available frontend-related skills/tools for the user's environment instead of coding.\n---\n\n# F Design\n\nUse this as the frontend entry skill. It is not a single visual style; it controls product thinking, approval, implementation, and production verification.\n\n## Reference Routing\n\nRead only the references required by the task:\n\n- Existing repository or substantial implementation: `references/project-intelligence.md`.\n- New screen, major redesign, ambiguous direction, or workflow change: `references/design-process.md`.\n- Any artifact created for user review: `references/artifact-presentation.md`.\n- Approved Level 2 or multi-state/multi-route implementation: `references/implementation-contract.md`.\n- API, form, permissions, async, mutation, or non-trivial state: `references/state-and-data.md`.\n- Stack-specific implementation decisions: matching section of `references/framework-adapters.md`.\n- Substantial implementation verification: `references/quality-gates.md`.\n- UI/UX review request: `references/review-rubric.md`.\n- Existing product/page design evaluation, pros/cons critique, or actionable improvement report: `references/product-design-review.md`, `references/review-rubric.md`, and `references/anti-ai-design-tells.md` when visual quality or generic AI-looking UI is in scope.\n- Specialized review targets: use the matching file under `references/review-templates/` for data tables, dashboards, complex forms, mobile navigation, or high-risk batch actions.\n- Release-level workflow verification or maintainer work: `references/end-to-end-journeys.md`.\n- Internationalization, CLI language selection, or translated maintainer docs: `references/internationalization.md`.\n\n## Context Files\n\nBefore substantial work, look for preference files in this order:\n\n1. `.design-guide/profile.md` in the current project.\n2. `~/.design-guide/preferences.md` on the local machine.\n3. `references/design-defaults.md` bundled with this skill.\n\nRead only the files that exist and are relevant. Project and local files override bundled defaults. Keep personal preferences out of the skill folder so the skill remains open-source friendly.\n\n## Invocation Modes\n\n### Mode 1: Navigation\n\nUse this mode when the user only says `design-guide`, `@design-guide`, `/design-guide`, \"use des"},{"path":"README.md","content":"

\n \n \n \n \"design-guide\n \n

\n\n# design-guide\n\nEnglish | [简体中文](README.zh-CN.md)\n\n[![Validate](https://github.com/GrubbyLee/design-guide/actions/workflows/validate.yml/badge.svg)](https://github.com/GrubbyLee/design-guide/actions/workflows/validate.yml)\n[![Sync to Gitee](https://github.com/GrubbyLee/design-guide/actions/workflows/sync-to-gitee.yml/badge.svg)](https://github.com/GrubbyLee/design-guide/actions/workflows/sync-to-gitee.yml)\n[![Release](https://img.shields.io/github/v/release/GrubbyLee/design-guide)](https://github.com/GrubbyLee/design-guide/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n> A frontend design orchestration skill for Codex, Claude Code, Cursor, Qwen Code, and other AI development environments.\n\n`design-guide` is not another UI style preset. It is a frontend design and production engineering control skill: it helps an AI coding agent understand a repository, choose and present a design direction, lock an executable contract, implement the UI, and verify behavior and quality before delivery.\n\nCurrent version: **v0.1.1**. See [AIDE compatibility](COMPATIBILITY.md) for separate installed, synchronized, and provider-invoked evidence. Chinese release notes are available in [中文兼容性](COMPATIBILITY.zh-CN.md).\n\nUse it when you want fewer generic AI-looking interfaces and a more disciplined frontend design/development loop.\n\n## What It Does\n\n- Acts as a frontend entry skill and navigator.\n- Supports two modes:\n - **Navigation mode**: invoked without a concrete task, it lists the best frontend tasks and helper skills available in the environment.\n - **Execution mode**: invoked with a real task, it follows a structured design-to-implementation workflow.\n- Scales the design process from direct fixes to exploratory design, based on uncertainty and the cost of reversing a decision.\n- Produces and presents reviewable artifacts such as wireframes, standalone HTML prototypes, reference boards, images, or motion studies when they are needed.\n- Automatically opens standalone HTML on a shared local desktop, manages HTTP review servers when needed, and uses host-accessible links or screenshots in remote environments.\n- Pauses at explicit confirmation gates so the user can approve, choose a direction, or request changes before expensive implementation.\n- Routes tasks such as dashboards, admin panels, landing pages, redesigns, screenshot-to-code work, mobile UI, animation, 3D, and UI reviews.\n- Evaluates existing product/page designs by mode, scores strengths and weaknesses, flags generic AI-design tells, and outputs prioritized, actionable improvement plans with evidence, tradeoffs, acce"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7fzmvcq3sggwf0kjtbz67mwx8bqeq9\",\n \"slug\": \"f-design-2\",\n \"version\": \"0.1.2\",\n \"publishedAt\": 1786205413728\n}"},{"path":"references/aide-integration.md","content":"# AIDE Integration\n\nUse this reference only when the user asks how to install, sync, or invoke `design-guide` across AI development environments.\n\n## Local Source of Truth\n\nPrimary folder:\n\n```text\n~/.codex/skills/design-guide\n```\n\nUse the current repository as the source of truth. A conventional Codex installation uses the folder above; the sync script safely skips it when source and target are identical.\n\n## Known Local Targets\n\nSupported local skill roots:\n\n```text\n~/.codex/skills\n~/.claude/skills\n~/.cursor/skills\n~/.qwen/skills\n```\n\nRecommended install paths:\n\n```text\n~/.codex/skills/design-guide\n~/.claude/skills/design-guide\n~/.cursor/skills/design-guide\n~/.qwen/skills/design-guide\n```\n\n## Invocation Guide\n\n- Codex: \"use design-guide\", `design-guide`, `$design-guide`, or `@design-guide` if the interface supports it.\n- Claude Code: `/design-guide` when installed as a Claude skill; otherwise say \"use design-guide\".\n- Cursor: say \"use design-guide\"; if it does not detect the skill, point it to the local `SKILL.md`.\n- Qwen Code: say \"use design-guide\"; if it does not detect the skill, point it to the local `SKILL.md`.\n- Unknown AIDE: add the folder to the tool's skill/rule/context directory, or paste the `SKILL.md` path and ask the agent to follow it.\n\n## Sync\n\nRun:\n\n```bash\nbash ~/.codex/skills/design-guide/scripts/sync-aide.sh\n```\n\nThe script copies the source folder into Codex, Claude, Cursor, and Qwen skill directories. It skips any target that resolves to the source itself.\n\nEach target is a managed mirror. Files that no longer exist in the source are removed. Repository metadata, temporary review artifacts, generated Python caches, and `.design-guide/profile.md` are excluded.\n\nFor an isolated verification or managed environment, redirect only the target root:\n\n```bash\nF_DESIGN_TARGET_HOME=/path/to/sandbox \\\n bash ~/.codex/skills/design-guide/scripts/sync-aide.sh\n```\n\nThe source can be overridden independently with `F_DESIGN_SRC`.\n\nThe sync command ends with a strict doctor check. A successful copy is not reported as synchronized until every public-file digest matches the source.\n\n## Version And Upgrade Diagnosis\n\nCheck the repository version and every local AIDE mirror:\n\n```bash\npython3 scripts/design-guide-doctor.py --strict\n```\n\nMachine-readable output:\n\n```bash\npython3 scripts/design-guide-doctor.py --strict --json\n```\n\nUpgrade a Git clone source, verify it, and synchronize the local mirrors:\n\n```bash\ngit -C ~/.codex/skills/design-guide pull --ff-only\npython3 ~/.codex/skills/design-guide/scripts/design-guide-doctor.py\nbash ~/.codex/skills/design-guide/scripts/sync-aide.sh\n```\n\nIf the active source is another checkout, set `F_DESIGN_SRC` explicitly before syncing. Restart or reload each AIDE after an upgrade when it caches skill discovery.\n\n## Compatibility Verification\n\nUse three levels of evidence and report them separately:\n\n1. **Installed:** the AIDE CLI and its `design-guide/SKILL.md` path exist.\n2. **Synchronized:** the installed "},{"path":"references/anti-ai-design-tells.md","content":"# Anti-AI Design Tell Review\n\nUse this as a companion to `references/product-design-review.md` and `references/review-rubric.md` when the user asks for design critique, redesign readiness, visual polish, or says the interface looks generic, templated, or AI-generated.\n\nThis file is not a style preference list. Treat each item as a diagnostic signal. A pattern is only a finding when it harms product fit, task clarity, trust, originality, accessibility, or conversion.\n\n## High-Confidence Tells\n\nFlag these with evidence when visible:\n\n- Default AI purple/blue gradients, neon glows, or decorative mesh backgrounds with no brand rationale.\n- Three equal feature cards or repeated equal cards where the content has different importance.\n- Centered hero with vague headline, vague subtext, and generic CTA.\n- Fake dashboard, fake terminal, or fake product preview built from decorative rectangles instead of a real screenshot, generated asset, or actual component.\n- Fake-precise metrics such as `99.9%`, `10x`, `48k`, or `92%` without source, label, or sample context.\n- Decorative status dots, version labels, build metadata, or weather/time/location strips that do not convey real state.\n- Overused eyebrow labels on every section, especially numbered labels such as `01`, `002`, `INDEX`, or `PHASE`.\n- Mixed visual systems: inconsistent radius, icon families, shadows, typography, button styles, or neutral palettes.\n- Card nesting and section-as-card structure that hides hierarchy instead of clarifying it.\n- Generic names, generic avatars, placeholder companies, or `Acme`-style brands presented as real content.\n- Copy that reads like filler: \"seamless\", \"elevate\", \"unlock\", \"next-gen\", \"effortless\", or poetic phrases that do not explain the product.\n\n## Product UI Tells\n\nFor dashboards, admin panels, tools, editors, and workbenches, also check:\n\n- Marketing-page hero structure used for an operational tool.\n- Excessive empty space that slows scanning in high-frequency work.\n- Metrics shown as decorative cards without drilldown, source, freshness, or action path.\n- Tables hidden behind card grids when users need comparison, sorting, filtering, or bulk action.\n- Every row action exposed equally instead of prioritizing common actions and protecting dangerous actions.\n- Bulk actions without impact summary, permission gating, confirmation, undo, or audit trail.\n- Empty/loading/error states omitted because only the successful demo state was designed.\n- High-risk AI outputs shown with opaque scores instead of explainable reasons and evidence.\n- Mobile layout merely squeezed from desktop, with fixed toolbars, clipped labels, or unreachable primary actions.\n\n## Marketing And Conversion Tells\n\nFor landing pages, homepages, pricing pages, and campaign pages, also check:\n\n- Hero value proposition could apply to any SaaS after changing the logo.\n- CTA labels change wording across nav, hero, pricing, and footer for the same intent.\n- Trust logos are plain text wordmarks or invent"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Frontend design, implementation, and production QA Skill: Design Guide Owner: grubbylee Summary: Frontend design, implementation, and production QA Tags: latest:0.1.2 Version history: v0.1.2 | 2026-08-08T16:10:13.728Z | auto - Initial release of f-design-2 v0.1.2 as \"design-guide\": a comprehensive frontend design and production engineering orchestrator. - Introduces structured reference routing for design, implementation, review, and environment-specific decisions. -","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1940,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T16:06:17.413Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:51:41.573Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}