[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6WWSV6ZMPZ547T99W2A5TV3":3,"skill-same:01M6WWSV6ZMPZ547T99W2A5TV3":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},"01M6WWSV6ZMPZ547T99W2A5TV3","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.10.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.10.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.10.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.10.0\u002Fcontext\u002Fskills\u002Fdesign\u002Ffrontend-design\u002Freferences\u002Faccessibility-checklist.md",[91,98,105,111,135,155],{"skillNo":92,"name":93,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":97},"01M7665G2ED3624R3X93304265","standard-ui-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-ui-design\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":97},"01M76651QTC6W0HJ4AFW2MMR3V","standard-agent-use","Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-use\u002FSKILL.md",[],[],{"skillNo":106,"name":107,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":97},"01M76650NN4T8P241021NBR64S","standard-agent-building","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-building\u002FSKILL.md",[],[],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":120,"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",[117],{"categoryNo":118,"categoryName":119,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[121,122,123,37,124,125,42,126,127,128,129,130,113,131,132,133,134],"management","skill management","ontology","create","as","transition","get","manage","update","alpha","list","package","skill package","manifests",{"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":142,"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",[141],{"categoryNo":118,"categoryName":119,"taxonomyType":21,"taxonomyTypeDesc":22},[143,144,121,145,146,147,148,149,150,151,152,153,42,127,128,130,154],"schema","schema management","contract","rebuild","contracts","workflows","wed","generated","MCP","validation","deterministic","mode",{"skillNo":156,"name":157,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":161,"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",[],[162,121,163,164,124,165,166,167,42,127,168,169,129,170,130,171,172,173,174,175],"proposition management","proposition","interface","claims","record","world","creation","event","WSJF","index","updates","query","facts","log"]