[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6WY25548CVGHC2PNGAFZVRJ":3,"skill-same:01M6WY25548CVGHC2PNGAFZVRJ":90},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":51,"linkOnly":52,"markdownContent":53,"markdownBody":54,"frontMatter":55,"refName":63,"commitSha":64,"skillDirectory":65,"forksCount":14,"repositoryHtmlUrl":66,"repositoryHomepageUrl":67,"ownerHtmlUrl":68,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":69,"install":70,"resources":83},"01M6WY25548CVGHC2PNGAFZVRJ","frontend-design",null,"Frontend architecture and UI design — component hierarchies, accessibility, performance, state management. Use when designing frontend architecture, building component hierarchies, making something accessible, optimizing Core Web Vitals, or choosing a state management approach.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fdesign\u002Ffrontend-design\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[32,33,34,35,36,5,37,38,39,40,41,42,43,44,45,46,47,48,49,50],"design","frontend design","frontend","when","vitals","v1","designing frontend","web vitals","ui design","use","work","ui","state","frontend architecture","state management","core","architecture","component","performance","2026-11-10 10:12:30",false,"---\nname: frontend-design\ndescription: |\n  Frontend architecture and UI design — component hierarchies, accessibility, performance, state management. Use when designing frontend architecture, building component hierarchies, making something accessible, optimizing Core Web Vitals, or choosing a state management approach.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv1\n    id: SKILL-frontend-design\n    version: \"1.1.0\"\n    created: 2026-04-06T00:00:00Z\n    category: design\n---\n\n# Frontend Design\n\n## Intro\n\nGood frontend design starts with semantic HTML, small\nsingle-responsibility components, and WCAG 2.2 AA accessibility, then\nlayers on performance, state management, and rendering strategy as the\napp grows. Apply these conventions when designing or reviewing any\nfrontend application.\n\n## Overview\n\n### Component architecture\n\nBuild a tree of small, single-responsibility components. Separate\ncontainer (data\u002Flogic) from presentational (UI) components, and\nco-locate related files (`Button\u002FButton.tsx`, `Button.test.tsx`,\n`Button.module.css`). Prefer composition — children and slots — over\ndeep prop configuration. Name components by what they are\n(`UserAvatar`), not where they live (`SidebarIcon`).\n\n### Semantic HTML first\n\nStart with the correct HTML element before reaching for ARIA:\n\n- `\u003Cnav>`, `\u003Cmain>`, `\u003Caside>`, `\u003Cheader>`, `\u003Cfooter>` for landmarks.\n- `\u003Cbutton>` for actions, `\u003Ca>` for navigation — never\n  `\u003Cdiv onClick>`.\n- `\u003Cul>` \u002F `\u003Col>` for lists, `\u003Ctable>` for tabular data.\n- `\u003Ch1>` through `\u003Ch6>` in logical order, no skipping levels.\n- `\u003Cdialog>` for modals, `\u003Cdetails>` for disclosure widgets.\n\nEvery `\u003Cimg>` needs `alt` (use `alt=\"\"` for decorative images). Every\nform input needs a visible `\u003Clabel>` with matching `for` \u002F `id`. Add\nARIA only when HTML semantics are insufficient.\n\n### Accessibility (WCAG 2.2 AA)\n\n- Keyboard navigation: all interactive elements reachable and\n  operable via keyboard.\n- Focus management: visible indicator, logical tab order, no focus\n  traps.\n- Color contrast: 4.5:1 normal text, 3:1 large text and UI\n  components.\n- Target size: at least 24x24 CSS pixels (WCAG 2.5.8).\n- Motion: respect `prefers-reduced-motion`; no auto-playing\n  animations over 5 seconds.\n- Error handling: identify errors clearly, suggest corrections,\n  prevent data loss.\n- Screen readers: `aria-live` for dynamic updates, `aria-label` for\n  icon buttons.\n- Authentication: no cognitive-function tests (WCAG 3.3.8).\n\nSee Level 3 for the full WCAG 2.2 AA checklist.\n\n### State management\n\nPick the simplest approach that fits the complexity:\n\n| Complexity        | Solution                                               |\n|-------------------|--------------------------------------------------------|\n| Local UI state    | `useState`, `useReducer`                               |\n| Shared across few | Lift state up, prop drilling (if shallow)              |\n| Shared across many| React Context (low-frequency updates)                  |\n| Complex global    | Zustand (simple API), Jotai (atomic), Redux (large teams) |\n| Server state      | TanStack Query \u002F SWR (caching, revalidation, dedup)    |\n| URL state         | Search params via router (`useSearchParams`)           |\n| Form state        | React Hook Form or Conform (validation, performance)   |\n\nAvoid putting everything in global state — most state is local.\nServer state is not client state; use a dedicated data-fetching\nlibrary. Derive computed values instead of storing them separately.\n\n### React \u002F Next.js patterns\n\nServer Components (default in App Router) fetch data on the server\nand ship zero JS. Add `\"use client\"` only when you need interactivity,\nhooks, or browser APIs. Use `\u003CSuspense>` boundaries to stream UI\nprogressively. Fetch data in Server Components and use TanStack Query\nfor client mutations. Pick a rendering strategy per route: SSG for\nstatic, SSR for personalized, ISR for hybrid. Export `metadata` or\n`generateMetadata` for SEO on each route.\n\n### Performance (Core Web Vitals)\n\nOptimize to the three Core Web Vitals thresholds:\n\n- **LCP (\u003C 2.5s):** preload hero images, use `next\u002Fimage` with\n  `priority`, minimize render-blocking CSS\u002FJS, inline critical CSS,\n  lean on Server Components to cut client JS.\n- **INP (\u003C 200ms):** avoid long tasks on the main thread, break work\n  with `startTransition`, debounce expensive handlers, virtualize\n  long lists, use `useOptimistic` for instant feedback.\n- **CLS (\u003C 0.1):** set explicit `width` \u002F `height` on media, reserve\n  space for dynamic content with skeletons, never inject content\n  above existing content.\n\nAnalyze bundles with `@next\u002Fbundle-analyzer`, lazy-load heavy\ncomponents, and load fonts via `next\u002Ffont` for zero layout shift.\n\n### Styling approaches\n\n| Approach       | Best for                        | Trade-offs                       |\n|----------------|---------------------------------|----------------------------------|\n| Tailwind CSS   | Rapid development, consistency  | Long class strings, learning curve |\n| CSS Modules    | Scoped styles, small bundles    | More files, less dynamic         |\n| Vanilla CSS    | Simple projects, standards      | No scoping, manual organization  |\n| CSS-in-JS      | Dynamic styles, co-location     | Runtime cost, SSR complexity     |\n\nPrefer Tailwind or CSS Modules for new projects (zero runtime cost).\nAvoid runtime CSS-in-JS in Server Components. Use CSS custom\nproperties for theming and keep design tokens in one place.\n\n### Project structure (Next.js App Router)\n\n```\nsrc\u002F\n  app\u002F                    # Routes, layouts, pages\n    (marketing)\u002F          # Route groups\n    dashboard\u002F\n      page.tsx\n      loading.tsx\n      error.tsx\n    layout.tsx\n    globals.css\n  components\u002F\n    ui\u002F                   # Shared primitives (Button, Input, Card)\n    features\u002F             # Feature-specific components\n  lib\u002F                    # Utilities, helpers, constants\n  hooks\u002F                  # Custom React hooks\n  types\u002F                  # Shared TypeScript types\n```\n\nGroup by feature for large apps, by type for small ones. Keep\n`components\u002Fui\u002F` framework-agnostic where possible, and export barrel\nfiles (`index.ts`) only for public component APIs.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Using `\u003Cdiv onClick>` instead of `\u003Cbutton>` for interactive elements.** A `\u003Cdiv>` is not keyboard-focusable, has no implicit ARIA role, and does not fire click events on Enter\u002FSpace. Keyboard users and assistive technology users cannot interact with it. Use the correct semantic HTML element first.\n- **Putting all state in a global store.** Global stores cause unrelated components to re-render on every update and make the data flow hard to trace. Most state is local; lift it up only when genuinely shared; use a dedicated data-fetching library for server state.\n- **Adding `\"use client\"` to a Next.js component to \"make it work\" without understanding why.** Every `\"use client\"` boundary ships JavaScript to the browser. Adding it to a parent makes every descendant a client component. Diagnose why the component needs interactivity and push the boundary as far down the tree as possible.\n- **Hardcoding colors, font sizes, or spacing values in components.** Hardcoded values bypass the design token system and make theming, dark mode, and accessibility changes require a search-and-replace across the codebase. Define tokens in one place and reference them everywhere.\n- **Omitting `alt` on images or using generic text like \"image\".** An `\u003Cimg alt=\"image\">` is meaningless to a screen reader user. Decorative images need `alt=\"\"` to be skipped; meaningful images need descriptive text that conveys their content.\n- **No `aria-live` for dynamic updates.** When content changes without a page reload (search results, error messages, toast notifications), assistive technology does not announce the change unless a live region is used. Wrap dynamic status updates in an `aria-live=\"polite\"` region.\n- **Optimizing Core Web Vitals last.** LCP, INP, and CLS regressions are cheapest to fix when the component is first written. Setting explicit `width`\u002F`height` on images, using `priority` on above-fold images, and avoiding long main-thread tasks are design decisions, not afterthoughts.\n\n## Full reference\n\n### WCAG 2.2 AA checklist\n\nCriteria marked (A) are Level A; (AA) are Level AA. Both are required\nfor AA conformance.\n\n**Perceivable — Text alternatives:**\n\n- 1.1.1 Non-text Content (A) — all images, icons, and buttons have\n  descriptive `alt`; decorative images use `alt=\"\"` or CSS.\n\n**Perceivable — Time-based media:**\n\n- 1.2.1 Audio\u002FVideo Only (A) — transcripts for audio-only,\n  transcripts or audio descriptions for video-only.\n- 1.2.2 Captions Prerecorded (A) — synchronized captions on\n  prerecorded video.\n- 1.2.3 Audio Description (A) — audio description or descriptive\n  transcript for video.\n- 1.2.4 Captions Live (AA) — real-time captions for live audio.\n\n**Perceivable — Adaptable:**\n\n- 1.3.1 Info and Relationships (A) — semantic HTML for headings,\n  landmarks, lists, table headers; do not rely on visual styling.\n- 1.3.2 Meaningful Sequence (A) — DOM order matches visual reading\n  order.\n- 1.3.3 Sensory Characteristics (A) — instructions do not rely solely\n  on shape, color, size, or location.\n- 1.3.4 Orientation (AA) — content works in portrait and landscape.\n- 1.3.5 Identify Input Purpose (AA) — form fields use appropriate\n  `autocomplete` attributes.\n\n**Perceivable — Distinguishable:**\n\n- 1.4.1 Use of Color (A) — color is not the only cue.\n- 1.4.2 Audio Control (A) — auto-playing audio over 3s can be paused\n  or adjusted.\n- 1.4.3 Contrast Minimum (AA) — 4.5:1 normal text, 3:1 large text\n  (18pt+ or 14pt+ bold).\n- 1.4.4 Resize Text (AA) — readable and functional at 200% zoom.\n- 1.4.5 Images of Text (AA) — use real text, not images of text.\n- 1.4.10 Reflow (AA) — no horizontal scrolling at 320px viewport\n  (1280px at 400% zoom).\n- 1.4.11 Non-text Contrast (AA) — 3:1 for UI components and graphical\n  objects.\n- 1.4.12 Text Spacing (AA) — no content loss with overridden line\n  height (1.5x), paragraph spacing (2x), letter spacing (0.12em),\n  word spacing (0.16em).\n- 1.4.13 Content on Hover\u002FFocus (AA) — tooltips dismissible,\n  hoverable, persistent until dismissed.\n\n**Operable — Keyboard:**\n\n- 2.1.1 Keyboard (A) — all functionality keyboard-accessible.\n- 2.1.2 No Keyboard Trap (A) — focus can always move away.\n\n**Operable — Enough time & seizures:**\n\n- 2.2.1 Timing Adjustable (A) — time limits can be turned off or\n  extended.\n- 2.2.2 Pause, Stop, Hide (A) — auto-moving content over 5s can be\n  paused.\n- 2.3.1 Three Flashes (A) — no more than 3 flashes per second.\n\n**Operable — Navigable:**\n\n- 2.4.1 Bypass Blocks (A) — \"skip to main content\" link.\n- 2.4.2 Page Titled (A) — descriptive `\u003Ctitle>`.\n- 2.4.3 Focus Order (A) — logical tab order.\n- 2.4.4 Link Purpose (A) — link text describes the destination.\n- 2.4.5 Multiple Ways (AA) — at least two ways to find pages.\n- 2.4.6 Headings and Labels (AA) — descriptive headings and labels.\n- 2.4.7 Focus Visible (AA) — clearly visible focus indicator.\n- 2.4.11 Focus Not Obscured (AA) — focused elements not hidden by\n  sticky UI.\n\n**Operable — Input modalities:**\n\n- 2.5.1 Pointer Gestures (A) — multi-finger\u002Fpath gestures have\n  single-pointer alternatives.\n- 2.5.2 Pointer Cancellation (A) — actions fire on pointer up and can\n  be aborted.\n- 2.5.3 Label in Name (A) — visible label text is in the accessible\n  name.\n- 2.5.4 Motion Actuation (A) — shake\u002Ftilt has button alternatives.\n- 2.5.7 Dragging Movements (AA) — drag-and-drop has a non-drag\n  alternative.\n- 2.5.8 Target Size Minimum (AA) — interactive targets at least\n  24x24 CSS pixels.\n\n**Understandable:**\n\n- 3.1.1 Language of Page (A) — `\u003Chtml lang=\"...\">`.\n- 3.1.2 Language of Parts (AA) — `lang` attribute on foreign content.\n- 3.2.1 On Focus (A) — focus does not trigger unexpected changes.\n- 3.2.2 On Input (A) — input changes do not cause unexpected\n  navigation.\n- 3.2.3 Consistent Navigation (AA) — navigation order consistent\n  across pages.\n- 3.2.4 Consistent Identification (AA) — same functionality uses same\n  labels.\n- 3.3.1 Error Identification (A) — errors clearly described in text.\n- 3.3.2 Labels or Instructions (A) — visible labels or instructions.\n- 3.3.3 Error Suggestion (AA) — suggest how to fix errors.\n- 3.3.4 Error Prevention (AA) — reversible, verified, or confirmed\n  for legal\u002Ffinancial data.\n- 3.3.7 Redundant Entry (A) — previously entered info auto-populated.\n- 3.3.8 Accessible Authentication (AA) — no cognitive tests, allow\n  paste, support password managers.\n\n**Robust:**\n\n- 4.1.2 Name, Role, Value (A) — custom components expose name, role,\n  state via ARIA; prefer native HTML.\n- 4.1.3 Status Messages (AA) — dynamic status announced via\n  `aria-live` or `role=\"alert\"`.\n\n### ARIA patterns\n\n```html\n\u003C!-- Icon button -->\n\u003Cbutton aria-label=\"Close dialog\">\n  \u003Csvg aria-hidden=\"true\">...\u003C\u002Fsvg>\n\u003C\u002Fbutton>\n\n\u003C!-- Live region for dynamic updates -->\n\u003Cdiv aria-live=\"polite\" aria-atomic=\"true\">\n  3 items in cart\n\u003C\u002Fdiv>\n\n\u003C!-- Form with error -->\n\u003Clabel for=\"email\">Email\u003C\u002Flabel>\n\u003Cinput id=\"email\" type=\"email\" aria-invalid=\"true\" aria-describedby=\"email-error\">\n\u003Cp id=\"email-error\" role=\"alert\">Please enter a valid email address.\u003C\u002Fp>\n\n\u003C!-- Modal dialog -->\n\u003Cdialog aria-labelledby=\"dialog-title\">\n  \u003Ch2 id=\"dialog-title\">Confirm deletion\u003C\u002Fh2>\n  ...\n\u003C\u002Fdialog>\n```\n\nBase HTML skeleton:\n\n```html\n\u003C!DOCTYPE html>\n\u003Chtml lang=\"en\">\n\u003Chead>\n  \u003Cmeta charset=\"UTF-8\">\n  \u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  \u003Ctitle>Descriptive Page Title\u003C\u002Ftitle>\n\u003C\u002Fhead>\n\u003Cbody>\n  \u003Ca href=\"#main\" class=\"sr-only focus:not-sr-only\">Skip to main content\u003C\u002Fa>\n  \u003Cheader>\u003Cnav aria-label=\"Main\">...\u003C\u002Fnav>\u003C\u002Fheader>\n  \u003Cmain id=\"main\">...\u003C\u002Fmain>\n  \u003Cfooter>...\u003C\u002Ffooter>\n\u003C\u002Fbody>\n\u003C\u002Fhtml>\n```\n\n### Testing tools\n\n- **axe DevTools** — browser extension for automated checks.\n- **Lighthouse** — accessibility audit in Chrome DevTools.\n- **NVDA** (Windows) \u002F **VoiceOver** (macOS) — screen reader testing.\n- **Keyboard-only navigation** — unplug the mouse, test every flow.\n- **Colour Contrast Analyser** — verify contrast ratios.\n- **WAVE** — web accessibility evaluation tool.\n\n### Further reading\n\n- `references\u002Faccessibility-checklist.md` — source for the WCAG 2.2\n  AA checklist above.\n- [React documentation](https:\u002F\u002Freact.dev)\n- [Next.js documentation](https:\u002F\u002Fnextjs.org\u002Fdocs)\n- [Web Content Accessibility Guidelines 2.2](https:\u002F\u002Fwww.w3.org\u002FTR\u002FWCAG22\u002F)\n","# Frontend Design\n\n## Intro\n\nGood frontend design starts with semantic HTML, small\nsingle-responsibility components, and WCAG 2.2 AA accessibility, then\nlayers on performance, state management, and rendering strategy as the\napp grows. Apply these conventions when designing or reviewing any\nfrontend application.\n\n## Overview\n\n### Component architecture\n\nBuild a tree of small, single-responsibility components. Separate\ncontainer (data\u002Flogic) from presentational (UI) components, and\nco-locate related files (`Button\u002FButton.tsx`, `Button.test.tsx`,\n`Button.module.css`). Prefer composition — children and slots — over\ndeep prop configuration. Name components by what they are\n(`UserAvatar`), not where they live (`SidebarIcon`).\n\n### Semantic HTML first\n\nStart with the correct HTML element before reaching for ARIA:\n\n- `\u003Cnav>`, `\u003Cmain>`, `\u003Caside>`, `\u003Cheader>`, `\u003Cfooter>` for landmarks.\n- `\u003Cbutton>` for actions, `\u003Ca>` for navigation — never\n  `\u003Cdiv onClick>`.\n- `\u003Cul>` \u002F `\u003Col>` for lists, `\u003Ctable>` for tabular data.\n- `\u003Ch1>` through `\u003Ch6>` in logical order, no skipping levels.\n- `\u003Cdialog>` for modals, `\u003Cdetails>` for disclosure widgets.\n\nEvery `\u003Cimg>` needs `alt` (use `alt=\"\"` for decorative images). Every\nform input needs a visible `\u003Clabel>` with matching `for` \u002F `id`. Add\nARIA only when HTML semantics are insufficient.\n\n### Accessibility (WCAG 2.2 AA)\n\n- Keyboard navigation: all interactive elements reachable and\n  operable via keyboard.\n- Focus management: visible indicator, logical tab order, no focus\n  traps.\n- Color contrast: 4.5:1 normal text, 3:1 large text and UI\n  components.\n- Target size: at least 24x24 CSS pixels (WCAG 2.5.8).\n- Motion: respect `prefers-reduced-motion`; no auto-playing\n  animations over 5 seconds.\n- Error handling: identify errors clearly, suggest corrections,\n  prevent data loss.\n- Screen readers: `aria-live` for dynamic updates, `aria-label` for\n  icon buttons.\n- Authentication: no cognitive-function tests (WCAG 3.3.8).\n\nSee Level 3 for the full WCAG 2.2 AA checklist.\n\n### State management\n\nPick the simplest approach that fits the complexity:\n\n| Complexity        | Solution                                               |\n|-------------------|--------------------------------------------------------|\n| Local UI state    | `useState`, `useReducer`                               |\n| Shared across few | Lift state up, prop drilling (if shallow)              |\n| Shared across many| React Context (low-frequency updates)                  |\n| Complex global    | Zustand (simple API), Jotai (atomic), Redux (large teams) |\n| Server state      | TanStack Query \u002F SWR (caching, revalidation, dedup)    |\n| URL state         | Search params via router (`useSearchParams`)           |\n| Form state        | React Hook Form or Conform (validation, performance)   |\n\nAvoid putting everything in global state — most state is local.\nServer state is not client state; use a dedicated data-fetching\nlibrary. Derive computed values instead of storing them separately.\n\n### React \u002F Next.js patterns\n\nServer Components (default in App Router) fetch data on the server\nand ship zero JS. Add `\"use client\"` only when you need interactivity,\nhooks, or browser APIs. Use `\u003CSuspense>` boundaries to stream UI\nprogressively. Fetch data in Server Components and use TanStack Query\nfor client mutations. Pick a rendering strategy per route: SSG for\nstatic, SSR for personalized, ISR for hybrid. Export `metadata` or\n`generateMetadata` for SEO on each route.\n\n### Performance (Core Web Vitals)\n\nOptimize to the three Core Web Vitals thresholds:\n\n- **LCP (\u003C 2.5s):** preload hero images, use `next\u002Fimage` with\n  `priority`, minimize render-blocking CSS\u002FJS, inline critical CSS,\n  lean on Server Components to cut client JS.\n- **INP (\u003C 200ms):** avoid long tasks on the main thread, break work\n  with `startTransition`, debounce expensive handlers, virtualize\n  long lists, use `useOptimistic` for instant feedback.\n- **CLS (\u003C 0.1):** set explicit `width` \u002F `height` on media, reserve\n  space for dynamic content with skeletons, never inject content\n  above existing content.\n\nAnalyze bundles with `@next\u002Fbundle-analyzer`, lazy-load heavy\ncomponents, and load fonts via `next\u002Ffont` for zero layout shift.\n\n### Styling approaches\n\n| Approach       | Best for                        | Trade-offs                       |\n|----------------|---------------------------------|----------------------------------|\n| Tailwind CSS   | Rapid development, consistency  | Long class strings, learning curve |\n| CSS Modules    | Scoped styles, small bundles    | More files, less dynamic         |\n| Vanilla CSS    | Simple projects, standards      | No scoping, manual organization  |\n| CSS-in-JS      | Dynamic styles, co-location     | Runtime cost, SSR complexity     |\n\nPrefer Tailwind or CSS Modules for new projects (zero runtime cost).\nAvoid runtime CSS-in-JS in Server Components. Use CSS custom\nproperties for theming and keep design tokens in one place.\n\n### Project structure (Next.js App Router)\n\n```\nsrc\u002F\n  app\u002F                    # Routes, layouts, pages\n    (marketing)\u002F          # Route groups\n    dashboard\u002F\n      page.tsx\n      loading.tsx\n      error.tsx\n    layout.tsx\n    globals.css\n  components\u002F\n    ui\u002F                   # Shared primitives (Button, Input, Card)\n    features\u002F             # Feature-specific components\n  lib\u002F                    # Utilities, helpers, constants\n  hooks\u002F                  # Custom React hooks\n  types\u002F                  # Shared TypeScript types\n```\n\nGroup by feature for large apps, by type for small ones. Keep\n`components\u002Fui\u002F` framework-agnostic where possible, and export barrel\nfiles (`index.ts`) only for public component APIs.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Using `\u003Cdiv onClick>` instead of `\u003Cbutton>` for interactive elements.** A `\u003Cdiv>` is not keyboard-focusable, has no implicit ARIA role, and does not fire click events on Enter\u002FSpace. Keyboard users and assistive technology users cannot interact with it. Use the correct semantic HTML element first.\n- **Putting all state in a global store.** Global stores cause unrelated components to re-render on every update and make the data flow hard to trace. Most state is local; lift it up only when genuinely shared; use a dedicated data-fetching library for server state.\n- **Adding `\"use client\"` to a Next.js component to \"make it work\" without understanding why.** Every `\"use client\"` boundary ships JavaScript to the browser. Adding it to a parent makes every descendant a client component. Diagnose why the component needs interactivity and push the boundary as far down the tree as possible.\n- **Hardcoding colors, font sizes, or spacing values in components.** Hardcoded values bypass the design token system and make theming, dark mode, and accessibility changes require a search-and-replace across the codebase. Define tokens in one place and reference them everywhere.\n- **Omitting `alt` on images or using generic text like \"image\".** An `\u003Cimg alt=\"image\">` is meaningless to a screen reader user. Decorative images need `alt=\"\"` to be skipped; meaningful images need descriptive text that conveys their content.\n- **No `aria-live` for dynamic updates.** When content changes without a page reload (search results, error messages, toast notifications), assistive technology does not announce the change unless a live region is used. Wrap dynamic status updates in an `aria-live=\"polite\"` region.\n- **Optimizing Core Web Vitals last.** LCP, INP, and CLS regressions are cheapest to fix when the component is first written. Setting explicit `width`\u002F`height` on images, using `priority` on above-fold images, and avoiding long main-thread tasks are design decisions, not afterthoughts.\n\n## Full reference\n\n### WCAG 2.2 AA checklist\n\nCriteria marked (A) are Level A; (AA) are Level AA. Both are required\nfor AA conformance.\n\n**Perceivable — Text alternatives:**\n\n- 1.1.1 Non-text Content (A) — all images, icons, and buttons have\n  descriptive `alt`; decorative images use `alt=\"\"` or CSS.\n\n**Perceivable — Time-based media:**\n\n- 1.2.1 Audio\u002FVideo Only (A) — transcripts for audio-only,\n  transcripts or audio descriptions for video-only.\n- 1.2.2 Captions Prerecorded (A) — synchronized captions on\n  prerecorded video.\n- 1.2.3 Audio Description (A) — audio description or descriptive\n  transcript for video.\n- 1.2.4 Captions Live (AA) — real-time captions for live audio.\n\n**Perceivable — Adaptable:**\n\n- 1.3.1 Info and Relationships (A) — semantic HTML for headings,\n  landmarks, lists, table headers; do not rely on visual styling.\n- 1.3.2 Meaningful Sequence (A) — DOM order matches visual reading\n  order.\n- 1.3.3 Sensory Characteristics (A) — instructions do not rely solely\n  on shape, color, size, or location.\n- 1.3.4 Orientation (AA) — content works in portrait and landscape.\n- 1.3.5 Identify Input Purpose (AA) — form fields use appropriate\n  `autocomplete` attributes.\n\n**Perceivable — Distinguishable:**\n\n- 1.4.1 Use of Color (A) — color is not the only cue.\n- 1.4.2 Audio Control (A) — auto-playing audio over 3s can be paused\n  or adjusted.\n- 1.4.3 Contrast Minimum (AA) — 4.5:1 normal text, 3:1 large text\n  (18pt+ or 14pt+ bold).\n- 1.4.4 Resize Text (AA) — readable and functional at 200% zoom.\n- 1.4.5 Images of Text (AA) — use real text, not images of text.\n- 1.4.10 Reflow (AA) — no horizontal scrolling at 320px viewport\n  (1280px at 400% zoom).\n- 1.4.11 Non-text Contrast (AA) — 3:1 for UI components and graphical\n  objects.\n- 1.4.12 Text Spacing (AA) — no content loss with overridden line\n  height (1.5x), paragraph spacing (2x), letter spacing (0.12em),\n  word spacing (0.16em).\n- 1.4.13 Content on Hover\u002FFocus (AA) — tooltips dismissible,\n  hoverable, persistent until dismissed.\n\n**Operable — Keyboard:**\n\n- 2.1.1 Keyboard (A) — all functionality keyboard-accessible.\n- 2.1.2 No Keyboard Trap (A) — focus can always move away.\n\n**Operable — Enough time & seizures:**\n\n- 2.2.1 Timing Adjustable (A) — time limits can be turned off or\n  extended.\n- 2.2.2 Pause, Stop, Hide (A) — auto-moving content over 5s can be\n  paused.\n- 2.3.1 Three Flashes (A) — no more than 3 flashes per second.\n\n**Operable — Navigable:**\n\n- 2.4.1 Bypass Blocks (A) — \"skip to main content\" link.\n- 2.4.2 Page Titled (A) — descriptive `\u003Ctitle>`.\n- 2.4.3 Focus Order (A) — logical tab order.\n- 2.4.4 Link Purpose (A) — link text describes the destination.\n- 2.4.5 Multiple Ways (AA) — at least two ways to find pages.\n- 2.4.6 Headings and Labels (AA) — descriptive headings and labels.\n- 2.4.7 Focus Visible (AA) — clearly visible focus indicator.\n- 2.4.11 Focus Not Obscured (AA) — focused elements not hidden by\n  sticky UI.\n\n**Operable — Input modalities:**\n\n- 2.5.1 Pointer Gestures (A) — multi-finger\u002Fpath gestures have\n  single-pointer alternatives.\n- 2.5.2 Pointer Cancellation (A) — actions fire on pointer up and can\n  be aborted.\n- 2.5.3 Label in Name (A) — visible label text is in the accessible\n  name.\n- 2.5.4 Motion Actuation (A) — shake\u002Ftilt has button alternatives.\n- 2.5.7 Dragging Movements (AA) — drag-and-drop has a non-drag\n  alternative.\n- 2.5.8 Target Size Minimum (AA) — interactive targets at least\n  24x24 CSS pixels.\n\n**Understandable:**\n\n- 3.1.1 Language of Page (A) — `\u003Chtml lang=\"...\">`.\n- 3.1.2 Language of Parts (AA) — `lang` attribute on foreign content.\n- 3.2.1 On Focus (A) — focus does not trigger unexpected changes.\n- 3.2.2 On Input (A) — input changes do not cause unexpected\n  navigation.\n- 3.2.3 Consistent Navigation (AA) — navigation order consistent\n  across pages.\n- 3.2.4 Consistent Identification (AA) — same functionality uses same\n  labels.\n- 3.3.1 Error Identification (A) — errors clearly described in text.\n- 3.3.2 Labels or Instructions (A) — visible labels or instructions.\n- 3.3.3 Error Suggestion (AA) — suggest how to fix errors.\n- 3.3.4 Error Prevention (AA) — reversible, verified, or confirmed\n  for legal\u002Ffinancial data.\n- 3.3.7 Redundant Entry (A) — previously entered info auto-populated.\n- 3.3.8 Accessible Authentication (AA) — no cognitive tests, allow\n  paste, support password managers.\n\n**Robust:**\n\n- 4.1.2 Name, Role, Value (A) — custom components expose name, role,\n  state via ARIA; prefer native HTML.\n- 4.1.3 Status Messages (AA) — dynamic status announced via\n  `aria-live` or `role=\"alert\"`.\n\n### ARIA patterns\n\n```html\n\u003C!-- Icon button -->\n\u003Cbutton aria-label=\"Close dialog\">\n  \u003Csvg aria-hidden=\"true\">...\u003C\u002Fsvg>\n\u003C\u002Fbutton>\n\n\u003C!-- Live region for dynamic updates -->\n\u003Cdiv aria-live=\"polite\" aria-atomic=\"true\">\n  3 items in cart\n\u003C\u002Fdiv>\n\n\u003C!-- Form with error -->\n\u003Clabel for=\"email\">Email\u003C\u002Flabel>\n\u003Cinput id=\"email\" type=\"email\" aria-invalid=\"true\" aria-describedby=\"email-error\">\n\u003Cp id=\"email-error\" role=\"alert\">Please enter a valid email address.\u003C\u002Fp>\n\n\u003C!-- Modal dialog -->\n\u003Cdialog aria-labelledby=\"dialog-title\">\n  \u003Ch2 id=\"dialog-title\">Confirm deletion\u003C\u002Fh2>\n  ...\n\u003C\u002Fdialog>\n```\n\nBase HTML skeleton:\n\n```html\n\u003C!DOCTYPE html>\n\u003Chtml lang=\"en\">\n\u003Chead>\n  \u003Cmeta charset=\"UTF-8\">\n  \u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  \u003Ctitle>Descriptive Page Title\u003C\u002Ftitle>\n\u003C\u002Fhead>\n\u003Cbody>\n  \u003Ca href=\"#main\" class=\"sr-only focus:not-sr-only\">Skip to main content\u003C\u002Fa>\n  \u003Cheader>\u003Cnav aria-label=\"Main\">...\u003C\u002Fnav>\u003C\u002Fheader>\n  \u003Cmain id=\"main\">...\u003C\u002Fmain>\n  \u003Cfooter>...\u003C\u002Ffooter>\n\u003C\u002Fbody>\n\u003C\u002Fhtml>\n```\n\n### Testing tools\n\n- **axe DevTools** — browser extension for automated checks.\n- **Lighthouse** — accessibility audit in Chrome DevTools.\n- **NVDA** (Windows) \u002F **VoiceOver** (macOS) — screen reader testing.\n- **Keyboard-only navigation** — unplug the mouse, test every flow.\n- **Colour Contrast Analyser** — verify contrast ratios.\n- **WAVE** — web accessibility evaluation tool.\n\n### Further reading\n\n- `references\u002Faccessibility-checklist.md` — source for the WCAG 2.2\n  AA checklist above.\n- [React documentation](https:\u002F\u002Freact.dev)\n- [Next.js documentation](https:\u002F\u002Fnextjs.org\u002Fdocs)\n- [Web Content Accessibility Guidelines 2.2](https:\u002F\u002Fwww.w3.org\u002FTR\u002FWCAG22\u002F)\n",{"name":5,"metadata":56,"description":62},{"processkit":57},{"id":58,"created":59,"version":60,"category":32,"apiVersion":61},"SKILL-frontend-design",1775433600000,"1.1.0","processkit.projectious.work\u002Fv1","Frontend architecture and UI design — component hierarchies, accessibility, performance, state management. Use when designing frontend architecture, building component hierarchies, making something accessible, optimizing Core Web Vitals, or choosing a state management approach.\n","main","4876a92620ee792aac2ac9a1a806322d8a572367","archive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fdesign\u002Ffrontend-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-11 23:24:18",{"source":8,"skillName":5,"commands":71,"prompt":81,"zipAvailable":82},[72,75,78],{"tool":73,"command":74},"npx","npx skills add projectious-work\u002Fprocesskit --skill frontend-design",{"tool":76,"command":77},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill frontend-design",{"tool":79,"command":80},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill frontend-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fdesign\u002Ffrontend-design\u002FSKILL.md",true,[84],{"path":85,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Faccessibility-checklist.md","REFERENCE","参考文档",7630,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fdesign\u002Ffrontend-design\u002Freferences\u002Faccessibility-checklist.md",[91,115,135,156,173,191],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":100,"publishedAt":51},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[97],{"categoryNo":98,"categoryName":99,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[101,102,103,104,105,106,42,107,108,109,93,110,111,112,37,113,114],"management","skill management","create","update","package","alpha","list","manage","ontology","get","as","manifests","skill package","transition",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":122,"publishedAt":51},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[121],{"categoryNo":98,"categoryName":99,"taxonomyType":21,"taxonomyTypeDesc":22},[101,123,124,125,126,127,106,42,128,129,108,130,131,132,110,133,134],"schema","schema management","MCP","workflows","validation","generated","rebuild","contracts","wed","deterministic","contract","mode",{"skillNo":136,"name":137,"nameZh":6,"description":138,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":139,"categories":140,"keywords":141,"publishedAt":51},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[101,142,143,103,104,144,106,42,145,146,147,148,110,149,150,151,152,153,154,155],"proposition","proposition management","index","log","world","record","query","creation","event","interface","updates","facts","claims","WSJF",{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":160,"categories":161,"keywords":162,"publishedAt":51},"01M6X5KMQ83QN9M6MPWZM7344F","ontology-management","Manage generated v1 ontology entities that do not require a dedicated domain server.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fontology-management\u002FSKILL.md",[],[101,109,163,103,106,164,165,128,166,145,108,167,168,110,169,170,150,171,37,172],"ontology management","lifecycle","archive","roadmap","do","domain","iteration","keep","measurement","generic",{"skillNo":174,"name":175,"nameZh":6,"description":176,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":179,"publishedAt":51},"01M6X5KCY2DN3SM21RERSFNEBT","okf-compatibility","Import, export, and validate conformant Open Knowledge Format bundles.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fokf-compatibility\u002FSKILL.md",[],[180,181,182,183,106,184,185,186,42,187,188,189,190],"okf","compatibility","okf compatibility","validate","open","knowledge","format","export","bundles","bundle","import",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":197,"publishedAt":51},"01M6X5JA8S5PNGJVFW4EQY8T83","capability-management","Manage versioned Capability entities and their governed lifecycle.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fcapability-management\u002FSKILL.md",[],[101,198,199,103,104,144,106,164,42,107,145,200,108,147,110,170,150,151,201,114],"capability","capability management","queries","changes"]