AGENT SKILL

toybox-design-system

Builds the Pocket Arcade Toybox theme - tokens, palettes, fonts, type roles, makeStyles, AppText, RaisedSurface, hard shadows, motion. Use when touching colours, dark mode, palette.ts, fonts, sizes or a game's paint. Not for components (toybox-components), icons or contrast audits (accessibility).

License 许可
MIT
最近更新
2026-11-05
Stars
★ 0
Forks
0

01 前言 Front Matter

name
toybox-design-system
description
Builds the Pocket Arcade Toybox theme - tokens, palettes, fonts, type roles, makeStyles, AppText, RaisedSurface, hard shadows, motion. Use when touching colours, dark mode, palette.ts, fonts, sizes or a game's paint. Not for components (toybox-components), icons or contrast audits (accessibility).

02 资源文件 500

03 SKILL.md 正文

Toybox design system

Makes every Pocket Arcade Shell screen speak Toybox: one typed theme module holding the exact token values, a checked palette per game, the three bundled fonts behind AppText, and one press implementation (RaisedSurface) with hard shadows. A script proves the app repo matches the Toybox token file value by value.

Rules that must hold

  1. Colours come only from theme.colors and SHELL_COLORS[theme.scheme]. Games repaint paint, never shape; a literal hex in UI code silently breaks dark mode and the other 25 games.
  2. Theme modules hold the Toybox values exactly: copy the templates, never retype. tokens.ts, type-styles.ts, shell-colors.ts, motion.ts and fonts.ts are compared with assets/toybox-tokens.json, and so is the logo tile's typed-in LOGO_TILE_VARIANTS table (ui/logo-tile.tsx); a typo is a visible design drift on every screen.
  3. Every game palette is generated by write-palette.mjs and passes the Toybox palette rules. Text 4.5:1 on ground, surface and sunken, fills 3:1 off their edge or ground, one ink in light, colour-blind = standard. The script refuses paints that fail, so no unreadable screen ships.
  4. Raised means pressable, and RaisedSurface is the only press. Pressable controls get a hard shadow of their elevation and sink into it; a key that stays pushed in (chosen segment, disabled, busy) moves by layout (top: elevation), because VoiceOver and Maestro ignore transforms; panels, rows, chips and toasts lie flat. Never shadowRadius, shadowOpacity, shadowOffset, shadowColor or elevation styles: they blur, and blur is not Toybox. Every RaisedSurface press also runs the Shell's tap feedback (usePressFeedback() from app/press-feedback-context.tsx, the one audio seam ui/ may use), except a switch, whose handler plays the toggle feedback.
  5. Paint flat, keep corners blocky, edge every fill with ink, at the widths the references render. No gradients; radii from RADII or the component constants (14 is the largest control radius, never a pill or circle); 3 pt outline on controls and panels, 2 on tiles and stickers (STROKE.tile: the token file's 2.5 floored, because the references are Chrome renders and Chrome floors CSS borders to whole px). Icon strokes, die-cut rings and Skia strokes keep their token values. Light accent and pop fills are only 1.0 to 1.9:1 against the ground; the ink edge is what makes them visible.
  6. Text goes through AppText with a type role or component style, never a raw size. Display text wraps balanced (the design's text-wrap: balance, through useBalancedWrap), stat values use tabular figures (isTabular), and Persian display numbers (levelNumber, scoreValue) have a 1.45 line box so iOS never clips their digits. Lilita One for display roles, Rubik for text, Vazirmatn Bold/Regular in fa and ckb at the same sizes, game names in Lilita One isolated LTR; never fontWeight (the family is the weight) and no tracking except the game name.
  7. Line heights sit on the device pixel grid, and glyphs are never nudged. lineHeight = snapToPixels(fontSize * ratio) in the one shared use-localized-text-style.ts (22.44 -> 67/3 at 3x), never Math.round to points and never the raw fraction: React Native rounds every text box up to whole pixels, so either one drifts a tall screen from its reference (S11 ended 2.5 pt low). No per-size translateY, padding or margin on text; the CoreText vs Chrome glyph offset is measured by the parity gate, not fixed in layout. The one layout rule for glyphs comes from font metrics, not measurement: AppText's overflow guard centres a Vazirmatn line's overflow as Chrome does (iOS puts it all above the line and clips it; Android already centres it, so there the guard's pads only hold the ink and never move the line), inside a wrapper that keeps the line box and the testID.
  8. Every app bundles the five Toybox fonts and three OFL texts, byte for byte. A missing or different file falls back to the system font and breaks the look and the S11d licence list.
  9. Motion follows the Toybox table, with its reduce-motion alternative. 70 ms press, spring back with RELEASE_SPRING (mass 1, not Reanimated's default 4); no squash, loops or slaps when reduce motion is on; the 2 s hold-to-confirm timer never shortens.
  10. Shape before colour. Every state keeps its non-colour cue (check or dash, dashed edge and padlock, filled vs hollow star); that is why the colour-blind palette may equal the standard one.
  11. Danger text sits only on surface, sunken (a pressed danger row) or dangerFill (5.5, 4.68 and 4.52:1 in light; on the light ground it is 3.8:1); the palette rules check all three, and body text on dangerFill. The light dangerFill is #FFDCDF (owner decision O5), so the hold label passes in every fill state. Destructive controls keep the surface fill and turn text, icon and edge danger; they never use accent.

Workflow

  1. Always read references/principles-and-rules.md first: the concept, the four principles, the 16 rules and how each is checked.
  2. Setting up the Shell theme (once, or when a template changed). Read references/react-native-mapping.md. Copy every file under templates/packages/shell/src/ to the same path in the app repo (the file map in that reference lists them), plus templates/test/integration/toybox-palettes.test.ts. Keep the values; adapt only imports that differ in the repo.
  3. Giving a game its palette. For a design game (its paint is in the token file: Line Siege, Flock Tilt, Scrap Shove, Snare Snake, Merge Siege, Jump Chain, Stepstone, Swap Guard, Toggle Drop, Poker Drop, Trail Clear) run node ${CLAUDE_SKILL_DIR}/scripts/write-palette.mjs --game <id> from the repo root. For any other game read references/colour-tokens.md ("Painting a new game"), write a paint file shaped like examples/new-game-paint.json, run the script with --paint <file> --dry-run until it prints RESULT: PASS, then without --dry-run. Add one it for the app to test/integration/toybox-palettes.test.ts, and include a light and a dark Home screenshot in the owner report.
  4. Bundling the fonts. Read references/type-and-fonts.md ("Installing the fonts"). Copy templates/test/integration/toybox-font-glyphs.test.ts to test/integration/ (it reads each app's TTFs for the no-break space AppText rewrites). Copy the five TTFs and three *-OFL.txt from ${CLAUDE_SKILL_DIR}/assets/fonts/ into apps/<game>/assets/fonts/ and make sure the one expo-font plugin entry (Shell config, shell-plugins.ts) lists all five TTFs, not only Vazirmatn. shell-plugins.ts arrives at Shell step 8: at step 7 the checker prints a SKIP ... [font-plugin] due at Shell step 8 line for it, which is a pass; from step 8 on the entry is checked strictly.
  5. Styling a component or screen. Take sizes from references/layout-shape-tokens.md, text from references/type-and-fonts.md, timings from references/motion.md. Imitate examples/streak-card.tsx: makeStyles with const styles = StyleSheet.create(...); return styles;, tokens only, AppText variants and tones, RaisedSurface for the pressable part, hardShadow / dieCutRing / focusRing for static parts. Component measurements belong to the components.
  6. Contrast questions (a new paint, a text on a fill): references/contrast.md has every measured pair and the rule ids.
  7. Run the checks from the repo root and loop until all pass: npx tsc --noEmit -p packages/shell (and each touched app), npx eslint <changed paths> --max-warnings 0, npx jest --ci, then node ${CLAUDE_SKILL_DIR}/scripts/check-design-system.mjs .. Every FAIL line names the file, the rule and the fix; fix the code, never the token file.
  8. Report in plain words what changed, which checks passed, and any open owner decision it touches (references/decisions-and-open-issues.md). Ask before changing a token value the mockup fixed.

Definition of done

  • [ ] The theme modules in packages/shell/src/theme/, i18n/fonts.ts, i18n/use-localized-text-style.ts, ui/app-text.tsx, ui/raised-surface.tsx (with the tap feedback), ui/edged-face.tsx (the one solid-edged face: edge colour under, fill inside), ui/toybox-styles.ts (the tilt primitive: TILTED_LAYER holds shouldRasterizeIOS and renderToHardwareTextureAndroid; DIE_CUT_TILTED_LAYER and dieCutTiltedLayer give a part with the die-cut ring iOS's flag only, because Android's texture cuts the outset ring off at the part's box) and app/press-feedback-context.tsx exist with the template values, and their tests pass.
  • [ ] Line heights come from snapToPixels (the type-style and text-style tests pin 55/3, 67/3 and 77/3 at 3x, the Persian level number's 91/3 and the Persian score's 191/3: levelNumber and scoreValue are 1 / 1.45); STROKE.tile is 2; a pushed-in key has top: elevation; RaisedSurface takes isStretched; the light dangerFill is #FFDCDF.
  • [ ] AppText has the Persian overflow guard (wrapper View with the testID; the line shifts only on iOS), balances display text with ui/use-balanced-wrap.ts (functional state updates), maps isTabular to tabular figures and reports onLineCount; app-text.test.tsx, app-text-balance.test.tsx, app-text.android.test.tsx, use-balanced-wrap.test.ts and use-balanced-wrap.android.test.ts pass; no other glyph nudge in AppText.
  • [ ] LOGO_TILE_VARIANTS in ui/logo-tile.tsx (when the logo tile exists) equals the token file's components.logoTile.
  • [ ] Every app with a src/ folder has src/theme/palette.ts written by write-palette.mjs, and test/integration/toybox-palettes.test.ts has one passing it per app.
  • [ ] Every Expo app has the five Toybox TTFs and three OFL texts in assets/fonts/, byte-identical to assets/fonts/, and the expo-font plugin entry embeds all five.
  • [ ] No runtime file uses blurred shadows, gradients, pills, fontWeight, raw font sizes, tracking or colour literals.
  • [ ] npx tsc --noEmit, npx eslint --max-warnings 0 and npx jest --ci pass for the touched workspaces.
  • [ ] node ${CLAUDE_SKILL_DIR}/scripts/check-design-system.mjs . prints RESULT: PASS

Anti-patterns

  • Retyping a hex value or a size from memory. Values drift by one digit and nobody notices until parity fails; copy the template or run write-palette.mjs.
  • Fixing a contrast failure by editing the rule or the token file. Change the paint (keep the hue, move the lightness) and rerun; the token file changes only with an owner decision.
  • A soft iOS shadow "just for this card". Panels lie flat by design; if a card needs to look pressable it must be a RaisedSurface.
  • fontWeight: '700' on Lilita One or Rubik. iOS synthesises a fake bold; pick Rubik-Bold / Vazirmatn-Bold through AppText.
  • A second press implementation (opacity feedback, a hand-rolled translate). Every key must sink and spring the same way, and sound the same way; compose RaisedSurface.
  • Importing services/ into ui/ for the tap sound. ESLint's ui boundary rejects it; read usePressFeedback() from app/press-feedback-context.tsx.
  • Using the design-system checker's pass as proof a screen looks right. It proves tokens and bans; the look of a screen is proven by the visual-parity comparison.
  • Colour-blind palettes with different hues in the Shell. Toybox carries meaning by shape; board pieces are the place for colour-blind hues.
  • Rounding a line height to whole points, or nudging text by a point to match a screenshot. React Native rounds text boxes up to whole pixels, so only snapToPixels keeps boxes exact; a nudge breaks the heights. First compare the element's font size and line height in the reference .layout.json with the role you used.
  • Using the token file's 2.5 for a border. The references draw 2 (Chrome floors CSS borders); take STROKE or the component specs, never the raw token.
  • A Persian display role at line height 1.0 because Chrome's reference looked fine. Chrome lets glyphs overflow the line box, iOS clips them: the level-tile digits and the S7 score lost their tops. The level number and the score are 1 / 1.45; copy type-styles.ts from the template, which check-design-system compares with the token file (persian-number-clip).
  • Moving Persian text by a measured offset, or dropping the overflow guard. iOS puts a Vazirmatn line's whole overflow above the line box; the guard derives the shift from the font's ascent and descent and keeps the design's box in a wrapper. Without it Persian titles sat 3 pt high and digit tops were clipped.
  • A balance search that sets state from its closure, or probes wider after a failed probe. iOS sends onTextLayout and onLayout in one batch and sends nothing for an unchanged layout, so the search stalls on the device while Jest passes. Copy use-balanced-wrap.ts.
  • A blanket flexGrow on every key to make dialog keys equally tall. It grew every icon button by 6 pt; only a key in a dialog row passes isStretched.

Files in this skill

File What it is Read/run when
references/principles-and-rules.md Concept, principles, avoids, the 16 rules with why and check Workflow step 1, every time
references/colour-tokens.md Colour roles, three game paints, Shell constants, dark rules, painting a new game Palettes, colours, dark mode
references/type-and-fonts.md Faces, font install, type roles, 55 component text styles (one mockup override), script font table, line heights on the pixel grid and glyph placement vs the references Text, fonts, RTL type, a text parity failure
references/layout-shape-tokens.md Spacing, screen frame, radii, strokes, elevation, press offsets Sizing anything
references/motion.md Easings, the motion table, spring mass, reduce motion in code Any animation
references/contrast.md Measured contrast for all paints, the palette rule ids Contrast questions, new paints
references/react-native-mapping.md File map, makeStyles recipes, RaisedSurface, static shadows, RTL rules Workflow step 2
references/decisions-and-open-issues.md Chosen values, undrawn states, open owner decisions Reporting, before changing a value
templates/packages/shell/src/theme/ theme-types, tokens (STROKE as rendered, isTabular), type-styles (+ test: snapToGrid, lineHeightOf, rowLabelStrong, statListHeading, the Persian level number and score at 1.45), shell-colors (light dangerFill #FFDCDF), motion, theme-set, theme-context, use-theme, make-styles, theme-provider, contrast Workflow step 2 (copy)
templates/packages/shell/src/i18n/ fonts.ts (+ test) and use-localized-text-style.ts (+ test, snapToPixels); all four synced from the library, identical to the RTL skill's copies, do not edit here Workflow step 2 (copy)
templates/packages/shell/src/ui/ app-text (the Persian overflow guard, balanced display text, tabular figures, onLineCount, on Android a break point after each in-word hyphen, a no-break space drawn as a plain space between two word joiners in Lilita One only (it has no U+00A0, and Android's fallback space is 1.7 pt wider: German "62 %" and "1,99 €"; Rubik and Vazirmatn draw their own, as wide as their space, which the root templates/test/integration/toybox-font-glyphs.test.ts reads from the TTFs: hasOwnNoBreakSpace) and, in a right-to-left layout, a right-to-left mark before a text without a strong letter (androidMarksOf in line-breaks, + test; the label stays the text as written), as Chrome and iOS break "right-to- / left" and as a TextView laid "۲۸ / ۲۷۰", and greedy line breaking (textBreakStrategy="simple"), as Chrome and iOS fill each line; tests app-text.test.tsx, app-text-balance.test.tsx and app-text.android.test.tsx, the Android guard, in the unit-android project), use-scaled-size (useScaledSize(): the size the phone draws a text size or line height at, linear up to MAX_TEXT_SCALE = 2 on iOS and before Android 14, along AOSP's font scale curves on Android 14 and later, from the pure font-scale-curve.ts; each with its test, the Android ones in unit-android, with app-text-scale.android.test.tsx for AppText's room), use-text-room (useTextRoom: AppText's room under its last line, counted on the text as drawn, with fitOf, countOf and afterReport, tested in app-text.test.tsx), use-balanced-wrap (+ test, with the device-measured S11c sequence, and use-balanced-wrap.android.test.ts in the unit-android project: Android counts a line's hanging trailing space in its reported width, so a probe can keep a line that reads wider than its room, and no layout is stale there), raised-surface (isStretched), edged-face (EdgedFace: a solid-edged face painted in its edge colour with the fill laid inside, so no pale hairline bleeds past a rounded corner; RaisedSurface's keys and DialogCard draw through it), toybox-styles (hard shadow, rings, and the tilt primitive with the iOS and Android layer flags; each with its test) Workflow step 2 (copy)
templates/packages/shell/src/app/press-feedback-context.tsx PressFeedbackProvider/usePressFeedback, the one press-feedback context ui/ reads (imports only React; ShellApp provides it with playUiFeedback(services, 'tap')); synced from the library, identical to the audio skill's copy, do not edit here Workflow step 2 (copy)
templates/packages/shell/src/app/press-feedback-context.test.tsx Its test (silent without the provider, runs the provider's feedback); synced from the library Workflow step 2 (copy)
templates/packages/shell/src/testing/ test-palette.ts, toybox-palette-checks.ts Workflow step 2 (copy)
templates/apps/line-siege/src/theme/palette.ts A generated palette (what write-palette.mjs writes) To compare with a generated file
templates/test/integration/toybox-palettes.test.ts Root test: every app palette passes the rules Workflow steps 2 and 3
templates/test/integration/toybox-font-glyphs.test.ts Root test: reads each app's TTFs and pins that only Lilita One lacks a no-break space (U+00A0), and that Rubik's and Vazirmatn's own is as wide as their space, as hasOwnNoBreakSpace says Workflow step 4, with the fonts
examples/streak-card.tsx A themed card with a raised key, tokens only Workflow step 5
examples/streak-card.test.tsx Its test (role, header, press, accessibility) Workflow step 5
examples/new-game-paint.json A passing paint file for a new game Workflow step 3
scripts/check-design-system.mjs Checker: theme values (strokes as rendered, type styles), the Persian level number and score at 1.45 (persian-number-clip), the logo tile table, pixel-grid line heights and no glyph nudges, the Persian overflow guard (arabic-overflow-guard, shifting only on iOS: overflow-guard-android), balanced display text (balanced-display), tabular stat values (tabular-digits), pushed-in keys sunk by layout, palettes, fonts (the expo-font entry SKIPs until shell-plugins.ts exists at Shell step 8), style bans Workflow step 7 and at the end
scripts/write-palette.mjs Generator: a game's palette.ts, validated first Workflow step 3
scripts/lib/ Token expectations, palette rules, TS module loading (used by the scripts) Never directly
scripts/selftest.mjs Proves both scripts on good and planted-bad fixtures After changing a script
scripts/check-lib.mjs Shared script helper, synced from the library (do not edit here) Never by hand
assets/toybox-tokens.json The Toybox token file (colours, type, sizes, motion, components, icons, logos) Read by the scripts; look up a value
assets/fonts/ LilitaOne, Rubik, Vazirmatn TTFs, OFL texts, SOURCES.md Workflow step 4 (copy)
assets/shared.json Declares the shared files this skill copies in (check-lib, tokens, fonts, the press-feedback context, i18n/fonts.ts and i18n/use-localized-text-style.ts, each with its test) When adding a shared file
tests/fixtures/ Good and planted-bad inputs for the self-test When adding a rule to a script

Related skills

  • toybox-components - every Toybox component built on this theme (buttons, rows, stickers, tiles, dialogs).
  • code-drawn-art-and-icons - the 41 icons, game logos, app icon and splash art.
  • toybox-screens - the S1 to S15 layouts that use these tokens.
  • toybox-visual-parity - proves a built screen matches its design screenshot.
  • accessibility - roles, labels, 200 % text and the contrast tests beyond palettes.
  • rtl-and-direction - direction, digits and bidi isolation.

04 同仓库更多 Skills

zakariaf
zakariaf/pocket-arcade

unit-and-component-tests

Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).

★ 0
zakariaf
zakariaf/pocket-arcade

typescript-and-lint-rules

Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).

★ 0
zakariaf
zakariaf/pocket-arcade

demo-skill

Builds a demo. Use when testing the pitfall checker.

★ 0
zakariaf
zakariaf/pocket-arcade

demo-skill

Builds a demo. Use when testing the pitfall checker.

★ 0
zakariaf
zakariaf/pocket-arcade

troubleshooting-playbook

Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).

★ 0
zakariaf
zakariaf/pocket-arcade

toybox-visual-parity

Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).

★ 0