yangshu2087 · yangshu2087 · Apr 2, 2026 · Apr 8, 2026 · Apr 8, 2026
@@ -0,0 +1,89 @@
+---
+name: frontend-design-review
+description: Review or implement front-end UI work with a design-first workflow. Use when the task involves page or component design quality, translating Figma or screenshot references into code, refining spacing or typography or responsive behavior, validating UI states, or checking visual polish before merge.
+---
+
+# Frontend Design Review
+
+Use this skill when Codex should behave like a design-aware front-end implementer instead of a generic code editor.
+
+## Inputs to gather first
+
+Read the highest-signal design inputs available before changing code:
+
+1. Repository `DESIGN.md`
+2. Workspace or repo design shortlist docs when present
+3. Figma links or node IDs
+4. Repository design files under `design/`
+5. Screenshots or reference images
+6. Existing component library and tokens
+7. Product spec or acceptance notes in repo docs, Notion, or Google Drive
+
+If a design source is missing, say so explicitly and continue with the strongest remaining source instead of pretending the design is fully specified.
+
+## Working rules
+
+1. Start from system constraints, not ad hoc CSS:
+   - identify framework, styling approach, component library, and token source
+   - prefer existing components and tokens over one-off values
+2. Break UI work into four layers:
+   - layout
+   - components
+   - states
+   - responsive behavior
+3. Cover non-happy paths by default:
+   - loading
+   - empty
+   - error
+   - hover
+   - focus-visible
+   - active
+   - disabled
+4. Keep accessibility in scope:
+   - semantic HTML first
+   - keyboard reachability
+   - visible focus states
+   - contrast awareness
+5. When implementing from Figma, preserve intent rather than copying every raw pixel token if that would fight the local design system.
+6. If using an external inspiration reference, state it explicitly and translate it into local rules rather than copying the original brand.
+
+## Verification loop
+
+Do not stop at “the code compiles.” Run a visual loop when possible:
+
+1. Launch the narrowest relevant preview or dev server.
+2. Inspect the page in a browser using the available browser automation skill.
+3. Check at least these widths when the UI is responsive:
+   - 375
+   - 768
+   - 1024
+   - 1440
+4. Look for:
+   - overflow or clipped content
+   - spacing inconsistency
+   - typography hierarchy issues
+   - broken alignment
+   - console errors
+   - missing interactive states
+5. If visual verification is not possible, state that gap explicitly.
+
+## Preferred local workflow
+
+In repositories that follow the workspace conventions:
+
+- inspect `DESIGN.md` first
+- inspect `docs/design-reference-shortlist.md` when present
+- inspect `design/design-system.md` if present
+- inspect `design/tokens.example.json` or the real token file if present
+- inspect `docs/ui-acceptance-checklist.md`
+- update `docs/agent-handoff.md` before pausing if design work is in progress
+
+## Output standard
+
+When summarizing work, include:
+
+1. what design inputs were used
+2. what external inspirations were chosen, if any
+3. what UI layers changed
+4. what states and breakpoints were checked
+5. what remains visually unverified
@@ -32,6 +32,8 @@
 - Use the team skill `webpage-capture-markdown` when a webpage should be preserved as a local markdown artifact instead of only summarized in chat.
 - Use `systematic-debugging` before proposing fixes for bugs, failures, or unexpected behavior.
 - Use `requesting-code-review` before merge or after major implementation work.
+- Use `docs/codex-capability-governance.md` and `docs/codex-capability-registry.md` as the workspace source of truth for capability layering, ownership, and retirement rules.
+- Run `scripts/codex-capability-audit.sh` before expanding the default skill/plugin/profile surface.
 - Activate vendored `playwright-best-practices` only when writing or stabilizing Playwright tests beyond basic browser automation.
 - Keep `skills-lock.json` in sync with installed or vendored marketplace skills.
 - Prefer preparing a safe upgrade plan and verification steps before changing binaries under `/Applications`.
@@ -60,6 +62,18 @@
 - Do not merge raw Stitch or AI Studio output straight to `main` without an explicit Codex or human cleanup pass.
 - When work starts from Stitch or AI Studio, record the artifact paths and intended next step in `docs/agent-handoff.md` before switching tools or opening a PR.
 
+## Front-end design workflow
+
+- For front-end tasks, prefer a design-first loop: design inputs -> implementation -> browser verification -> UI review.
+- Start with the highest-signal design artifact available: Figma, checked-in design docs, screenshots, or reference shots.
+- Read repository `DESIGN.md` before changing UI. In this workspace, `/Users/yangshu/Codex/DESIGN.md` is the team baseline when a repo has not defined a narrower design source of truth yet.
+- Use `/Users/yangshu/Codex/docs/design-reference-shortlist.md` as the approved inspiration map for external visual references. Pick 1-2 references that fit the task and translate them into local tokens and components instead of cloning them.
+- Keep front-end repo guidance close to the code by checking in `design/README.md`, `design/design-system.md`, and `docs/ui-acceptance-checklist.md` where UI work happens.
+- Use the workspace skill `frontend-design-review` for UI implementation and polish work that needs spacing, typography, states, responsive behavior, and visual verification.
+- Prefer tokenized values and reusable components over one-off CSS when refining UI.
+- When Context7 is authenticated, prefer it for current framework and component-library docs during front-end work.
+- Do not treat third-party `DESIGN.md` files as direct brand templates; adapt them into project-approved design rules first.
+
 ## Codex and Cursor shared protocol
 
 - Treat checked-in repository files as the shared baton between Codex and Cursor. Do not rely on chat memory to transfer state.
@@ -79,3 +93,10 @@
 
 - After changing Codex config or skills, verify with `codex --version`, `codex features list`, `codex mcp list`, and `scripts/check-codex-upgrade.sh`.
 - If behavior depends on project instructions, confirm Codex is launched from the intended directory so the nearest `AGENTS.md` wins.
+
+## DESIGN.md workflow
+
+- Keep repository-level `DESIGN.md` as the source of truth for look-and-feel constraints used by AI agents.
+- For front-end tasks, read `DESIGN.md` before implementation and follow its token, component, state, and responsive rules.
+- Use `/Users/yangshu/Codex/docs/design-reference-shortlist.md` only as inspiration calibration, not as permission to clone brand visuals.
+- Before finalizing UI work, run narrow code checks and at least one browser visual verification pass.
@@ -0,0 +1,219 @@
+# Workspace Design Language
+
+This `DESIGN.md` is the team-level design source of truth for Codex work in this workspace.
+
+It is intentionally not a copy of any one brand.  
+It is a synthesis of the approved reference set in [`docs/design-reference-shortlist.md`](/Users/yangshu/Codex/docs/design-reference-shortlist.md), with the strongest influence coming from:
+
+- Vercel
+- Linear
+- Stripe
+- Notion
+- Mintlify
+
+The target default is: **developer-tool SaaS with precise hierarchy, restrained surfaces, strong readability, and reusable component logic**.
+
+## 1. Visual Theme & Atmosphere
+
+The default visual mood should feel:
+
+- calm
+- engineered
+- trustworthy
+- modern
+- readable under long use
+
+Prefer **light-first public surfaces**:
+
+- marketing pages
+- pricing pages
+- docs pages
+- onboarding flows
+
+Use **dark product shells** only when they help dense logged-in workflows:
+
+- dashboards
+- lists and detail panes
+- settings
+- command-heavy product views
+
+Do not mix multiple strong visual worlds on the same page.  
+Choose one dominant mode and keep the rest supportive.
+
+## 2. Color Palette & Roles
+
+### Core neutrals
+
+- **Ink 900** `#171717`: primary headings, strong text, dark iconography
+- **Ink 700** `#4d4d4d`: secondary text, helper copy
+- **Ink 500** `#666666`: tertiary text, muted labels
+- **Ink 300** `#808080`: placeholders, disabled text
+- **Canvas** `#ffffff`: page background, major card surface
+- **Surface 50** `#fafafa`: subtle alternate surface
+- **Border** `#ebebeb`: dividers, input outlines, card edges
+
+### Primary interactive colors
+
+- **Action Blue** `#0a72ef`: primary action, selected state, key links
+- **Focus Blue** `#0072f5`: focus ring, accessibility-visible interaction
+- **Success Green** `#15be53`: success state, positive metric, completion cue
+- **Warning Amber** `#c37d0d`: warning and caution
+- **Danger Rose** `#cf2d56`: error and destructive state
+
+### Reserved accent colors
+
+- **Accent Indigo** `#5e6ad2`: allowed for AI / automation / active-navigation moments
+- **Accent Violet** `#7170ff`: allowed sparingly in dark authenticated product shells
+
+Rule:
+
+- On any one screen, use **one dominant chromatic accent**.
+- Secondary accent colors should appear only as small support signals, not as competing primaries.
+
+## 3. Typography Rules
+
+### Font families
+
+Use the repository-native font stack if one already exists.  
+If no strong existing stack exists, prefer:
+
+- **Sans**: `Geist Sans`, then `Inter`, then system fallback
+- **Mono**: `Geist Mono`, `Berkeley Mono`, or `ui-monospace`
+
+Avoid defaulting to generic Arial/system-only output when a more intentional stack already exists.
+
+### Hierarchy
+
+- **Display / Hero**: `48px-64px`, weight `600`, tight line height, negative tracking only when visually justified
+- **H1 / Section Headings**: `36px-48px`, weight `600`
+- **H2 / Subsections**: `28px-36px`, weight `600`
+- **H3 / Card Titles**: `20px-24px`, weight `600`
+- **Body**: `16px-18px`, line-height `1.5-1.7`
+- **Small UI / Meta**: `12px-14px`, weight `500`
+- **Code / Technical Labels**: monospace, small, high-contrast, sparse use
+
+Typography should feel compressed and intentional in headlines, but relaxed and highly legible in body text.
+
+## 4. Component Stylings
+
+### Buttons
+
+- Default height: `40px-44px`
+- Radius: `10px-12px`
+- Primary button: solid accent fill
+- Secondary button: neutral surface + subtle border
+- Tertiary button: text-first, low visual weight
+
+Use full-pill radius only for:
+
+- badges
+- segmented pills
+- small filter chips
+
+### Cards
+
+- Radius: `12px-16px`
+- Prefer border-first depth over heavy shadow
+- Use generous internal padding
+- Keep card content structured: title, supporting text, actions, status
+
+### Inputs and forms
+
+- Height: `40px-44px`
+- Border: subtle by default, stronger on hover/focus
+- Focus state must be visible and consistent
+- Labels should stay readable, never too faint
+
+### Navigation
+
+- Clear active state
+- Strong hierarchy over decoration
+- Minimal chrome
+- In dark shells, keep contrast high without neon excess
+
+## 5. Layout Principles
+
+- Use an `8px` spacing base
+- Prefer generous whitespace on public pages
+- Prefer tighter but still breathable density in logged-in product areas
+- Keep marketing widths around `1200px-1280px`
+- Keep reading content around `720px-840px`
+- Avoid cramming too many unrelated visual motifs into one section
+
+For public surfaces:
+
+- prioritize rhythm
+- visual grouping
+- scroll clarity
+
+For authenticated product surfaces:
+
+- prioritize scannability
+- alignment
+- fast task execution
+
+## 6. Depth & Elevation
+
+Default rule: **border first, shadow second**.
+
+Preferred depth system:
+
+- subtle border on most surfaces
+- micro-shadow only when a surface genuinely needs lift
+- stronger elevation only for dialogs, popovers, or featured cards
+
+Avoid:
+
+- muddy multi-color shadows
+- oversized glassmorphism
+- large blurred glows as a default pattern
+
+## 7. Do's and Don'ts
+
+### Do
+
+- reuse existing tokens and components
+- keep hierarchy obvious
+- verify hover, focus, loading, empty, error, and disabled states
+- match the repo's real design system before introducing new primitives
+- choose a small number of strong ideas and apply them consistently
+
+### Don't
+
+- clone third-party brand styles verbatim
+- mix Vercel minimalism, Cursor warmth, and Stripe luxury on one page
+- use multiple loud accent colors on the same screen
+- overuse gradients, glow, blur, or oversized animations
+- hide important structure behind stylistic flourishes
+
+## 8. Responsive Behavior
+
+Default verification widths:
+
+- `375`
+- `768`
+- `1024`
+- `1440`
+
+Rules:
+
+- mobile first for public flows
+- no clipped copy
+- no broken CTA alignment
+- no hidden states that exist only on desktop
+- preserve hierarchy rather than pixel identity when adapting across sizes
+
+## 9. Agent Prompt Guide
+
+When Codex works on front-end tasks in this workspace, it should:
+
+1. read this `DESIGN.md` first
+2. read [`docs/design-reference-shortlist.md`](/Users/yangshu/Codex/docs/design-reference-shortlist.md) if external inspiration is useful
+3. explicitly state which 1-2 references are relevant for the current task
+4. translate those references into repo-native tokens, components, and patterns
+5. verify at least one real browser or visual pass before claiming completion
+
+Prompting rule:
+
+- treat external references as **design-language input**
+- never treat them as **brand-cloning instructions**