From pixel-perfect
Auto-activating context for pixel-perfect projects. Detects manifest, injects phase awareness and adapter conventions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pixel-perfect:process-contextThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are working in a project managed by **pixel-perfect**, a 6-phase build process orchestrator that produces real code in the target framework, browsable in a **sandbox** — a `custom` native component browser by default (see `docs/sandbox-spec.md`), or Storybook only if `tools.sandbox` says so. This context was auto-loaded because `design/manifest.json` exists in the project.
You are working in a project managed by pixel-perfect, a 6-phase build process orchestrator that produces real code in the target framework, browsable in a sandbox — a custom native component browser by default (see docs/sandbox-spec.md), or Storybook only if tools.sandbox says so. This context was auto-loaded because design/manifest.json exists in the project.
If design/manifest.yaml exists but design/manifest.json does not, auto-migrate before proceeding:
design/manifest.yamldesign/manifest.jsondesign/manifest.yamlMigrated design/manifest.yaml → design/manifest.json
All data preserved. YAML file removed.
This migration is automatic and transparent. No user confirmation needed — JSON is the canonical format going forward.
If design/manifest.json exists and its platforms field is an array (v4.x format), auto-migrate to v5.0 object format before proceeding:
platforms object. For each platform name in the array, create a key with:
tools: copy from the top-level tools objectphase: copy from the top-level phasegates: copy scaffold, plan, atoms, molecules, compose from top-level gatesatoms: copy from top-level atoms (or [] if missing)molecules: copy from top-level molecules (or [] if missing)screens: copy from top-level screens (or [] if missing)gates with only: discover, target, equiptools, phase, atoms, molecules, screensversion to 5.0.0design/manifest.jsonMigrated manifest to v5.0.0 (multi-platform format).
Platforms: {list of platform keys}
All data preserved.
This migration is automatic and transparent. No user confirmation needed.
design/manifest.json.argType, or a labeled variant in a custom sandbox).Tokens/Design System, Components, Molecules, Organisms, Screens).docs/state-patterns.md for framework-specific state idioms.route, not by visual state. Collapse views that differ only by state (default/empty/loading/error, or different tabs of one page) into ONE screen carrying a states list; each state becomes its own sandbox story. The screen owns internal state and must be drivable into each listed state for those stories (the mechanism is an implementation/adapter detail). When the route/page layout is uncertain, ask the user. See docs/state-patterns.md (Screens: Route + States) for the state-vs-route decision rule.Before doing any component or screen work, read design/manifest.json to understand:
goal, vibe, spec, references (shared across all platforms)gates)platforms object — each key is a platform name containing:
tools: framework, style, components, icons, sandbox for this platformphase: current active phase for this platformgates: scaffold through compose gate status for this platformatoms, molecules, screens: component inventory for this platform. Each screens[] entry is keyed by route (the page identity / dedup key) and carries a states list (the named states for that route — each maps to one sandbox story). See docs/state-patterns.md.When a command operates on a specific platform, read platforms[platformName] for all platform-specific state.
Commands that operate on build phases (scaffold, build, verify, refine) are platform-scoped:
--platform flag is provided, prompt the user to choose--platform flag explicitly selects which platform to operate on| Current Phase | What You Should Do | What You Should NOT Do |
|---|---|---|
| discover | Help define goal and vibe | Write any code |
| target | Help select platforms, framework, style, components | Write any code |
| equip | Help confirm tool selections | Write any code |
| scaffold | Set up project, create theme, generate token stories for the selected platform | Build feature components |
| plan | Review the BUILD PLAN for the selected platform | Write component code |
| atoms | Build individual components for the selected platform | Skip to molecules or compose directly |
| molecules | Build functional atom compositions for the selected platform | Compose screens before molecules are verified |
| organisms | Build complex stateful compositions of molecules + atoms for the selected platform | Compose screens before organisms are verified |
| compose | Assemble screens from organisms, molecules, and atoms for the selected platform | Skip molecule/organism verification, wire data |
Important: Each platform progresses independently. One platform may be at compose: passed while another is at scaffold: in-progress. Always check the selected platform's gates, not another platform's.
A framework adapter (docs/adapters/{framework}.md) is loaded first when one exists for platforms[name].tools.framework (e.g. sveltekit); it governs project structure, Storybook setup, and story format. React/Next/Vite have no framework adapter and use the default React path in docs/adapters/storybook.md.
Based on the tools in the manifest, follow these conventions:
platforms[name].tools.framework is sveltekit:.svelte files authored with Svelte 5 runes ($props(), $state(), $derived()); use snippet children, not legacy slots.stories.svelte (native CSF via @storybook/addon-svelte-csf — defineMeta + <Story>) or .stories.ts (@storybook/svelte)$lib alias; supply SvelteKit load/route data through props (mock with parameters.sveltekit_experimental in stories)@storybook/sveltekit; see docs/adapters/sveltekit.mdplatforms[name].tools.style is tailwind/nativewind:text-primary, bg-secondary, etc.p-4, gap-6), not arbitrary valuessm:, md:, lg:) where neededplatforms[name].tools.components is shadcn:@/components/ui/cn() for conditional class mergingplatforms[name].tools.components is shadcn-svelte / bits-ui / skeleton:$lib/components/ui/, use cn() from $lib/utils, follow the CSS-variable theme (same tokens as shadcn)@skeletonlabs/skeleton-svelte components + Skeleton theme tokens; select the theme via data-themedocs/adapters/{components}.mdplatforms[name].tools.components is react-native-paper:useTheme() for dynamic valuesPaperProvider at app rootreact-native-web polyfillplatforms[name].tools.sandbox is custom (default):docs/sandbox-spec.md natively in the target framework (see docs/adapters/custom-sandbox.md): a layer-keyed story registry, a two-pane navigator, token codegen from theme.*.json, one run command.Palette) — components reference tokens, never hardcode.// Target: design/system/{layer}/{name}/dark.png).platforms[name].tools.sandbox is storybook:ComponentName.stories.tsx (React) or ComponentName.stories.svelte / .stories.ts (SvelteKit; follow the framework adapter)For full argTypes control conventions, see docs/storybook-conventions.md.
platforms[name].tools.sandbox is tui-sandbox:.story.ts format (not CSF3)stories/ directory (not with components)StoryMeta default export with title, adapter, terminal dimensionsmount or imperative run functionscreateTestHarness() for automated testingStories must use the correct hierarchy prefix:
| Category | Prefix | Example |
|---|---|---|
| Design tokens | Design System/ | title: 'Design System/Colors' |
| Atomic components | Components/ | title: 'Components/StatusBadge' |
| Molecule compositions | Molecules/ | title: 'Molecules/JobRow' |
| Organism compositions | Organisms/ | title: 'Organisms/DataTable' |
| Composed screens | Screens/ | title: 'Screens/TodayFeed' |
Note for TUI projects: Stories use the .story.ts format with StoryMeta in the default export, not CSF3. The hierarchy prefixes are the same, but the story file format differs.
Based on the project's framework, use the appropriate state pattern for molecules and organisms:
| Framework | Atom State | Molecule/Organism State | Reference |
|---|---|---|---|
| React/Vite/Next | None (props only) | useState / useReducer | docs/state-patterns.md |
| SvelteKit | None (props via $props()) | $state() / $derived() runes | docs/state-patterns.md |
| React Native/Expo | None (props only) | useState / useReducer | docs/state-patterns.md |
| SwiftUI | None (props) | @State / @Observable | docs/state-patterns.md |
| GPUI | None | Entity<T> + update() | docs/state-patterns.md |
| Bubbletea | None (functional params) | Model struct + Update() method | docs/state-patterns.md |
| Textual | None (functional params) | reactive() / @on | docs/state-patterns.md |
| Ink | None (props) | useState / useReducer (same as React) | docs/state-patterns.md |
Atoms must NEVER manage internal state. If state is needed, promote to a molecule or organism.
Screens are the top-level stateful level, planned as a route + a list of states (not one screen per state). The screen owns internal state to switch between its listed states and must be drivable into any listed state for its sandbox stories — the override mechanism (controlled/uncontrolled props, naming, precedence) is an implementation/adapter detail, not prescribed here. Use the same framework idiom above to own the internal state. To decide whether a tab/sub-view is a state of one route or a separate route, follow the state-vs-route decision rule in docs/state-patterns.md.
When building components that match complex UI patterns (data tables, date pickers, rich text editors, drag-and-drop, charts, etc.), the Ecosystem Scan during BUILD PLAN may recommend ecosystem libraries.
How library research works:
During build (Phase 4b Step 2b): The Ecosystem Scan automatically evaluates complex patterns against docs/library-vetting-rubric.md and recommends well-scored libraries (≥5/8).
Before build (standalone): /pixel-perfect:research --libraries "{pattern}" pre-researches libraries, saving scored results to design/research/libraries/.
Vetting: Every recommended library is scored on 8 criteria (maintenance, popularity, compatibility, bundle, a11y, license, tests, community). Score ≥5/8 required for recommendation.
Validation: Before building a wrapper, verify the package exists on npm (or equivalent registry), has no peer dependency conflicts, and imports successfully.
Manifest trail: Every used library records package, version, vetting score, research date, and tradeoffs in the manifest's ecosystemLibs.
When to research independently:
For design token story regeneration and the polyfill disclaimer pattern (required for React Native web Storybook), see docs/storybook-conventions.md and docs/adapters/react-native-web.md.
| Command | What It Does |
|---|---|
/pixel-perfect:wireframe | Phase 0 (optional, low-fi): ASCII wireframes from plans/targets into design/wireframes/ — a pre-step to design-deconstruct |
/pixel-perfect:design-deconstruct | Phase 0 (optional): deconstruct existing UI/concepts into HTML mockups that seed the build |
/pixel-perfect:init | Phases 1-3: discover + target + equip |
/pixel-perfect:add-platform | Add a new platform to an existing project (post-init) |
/pixel-perfect:scaffold | Phase 4: set up project structure, theme, token stories |
/pixel-perfect:build | Phases 4b-6: plan → atoms → molecules → compose |
/pixel-perfect:verify | Run gate checks for current phase |
/pixel-perfect:status | Show progress |
/pixel-perfect:research | Design research |
/pixel-perfect:refine | Iterate on code |
Fidelity ladder. When design/wireframes/ (structural ASCII) or design/system/ (high-fi HTML mockups) exist, build each screen/component to match the highest-fidelity target available (mockup > wireframe). These are targets/specs — the real components supersede them.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Searches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
npx claudepluginhub hackerpug-ai/pixel-perfect --plugin pixel-perfect