What is the design system structure skill?
The design-system-structure skill makes an AI coding agent keep every aesthetic value of a Flutter app in one directory. Tokens come in two tiers, widgets read them through a ThemeExtension, and a script fails the build on stray raw values.
The design-system-structure skill structures a Flutter design system as tokens, then theme, then modifiers, then shapes. It owns how tokens, themes, components and shapes are structured and consumed, and your design source of truth owns which values to pick.
The aim is a design system that cannot hold a stray opinion. Every aesthetic value lives in one directory, and every widget reads it back through a named slot, so a reskin becomes a diff of lib/theme.
The rules it enforces
- No raw aesthetic value outside lib/theme, with scripts/check_raw_values.sh as the gate.
- Two token tiers, where widgets read only the semantic tier.
- Tokens read through a ThemeExtension and an asserting of(context) with no fallback.
- A hand authored ColorScheme instead of ColorScheme.fromSeed.
- Light and dark authored by hand, each passing AA.
- Reduced motion collapsing to Duration.zero.
- The persisted theme restored before first paint.
Two tiers of tokens
Tier 1 primitives are named by the measured value, such as neutral12 for OKLCH lightness times 100, and never by rank, appearance or brand. Tier 2 semantic slots are named by role, such as surface, onSurface, hairline and accent.
A widget that reaches a Tier 1 primitive has hardcoded one theme. Rank scales have no room to insert and lie in dark mode, appearance names invert, and brand names die with the brand.
What ships with the skill
The skill folder holds the skill file plus examples, references and scripts. The references cover token tiers and ThemeExtension, motion and reduced motion, typography and fonts, and contrast with redundant encoding. The scripts are check_raw_values.sh and check_font_bundling.sh.
Who the design system structure skill is for
Best for
- Creating or editing ThemeData, ThemeExtension or ColorScheme in a Flutter app.
- Adding or renaming a design token, or structuring a theme or DesignSystem folder.
- Wiring theme injection or theme mode persistence.
- Reviewing any widget that renders a color, radius, duration or font.
Not for
- Choosing which colors or radii to use, since the skill owns structure and not values, so for building color ramps, naming semantic color tokens and measuring contrast pairs the better-colors skill fits.
- Token pipelines built on DTCG JSON or Style Dictionary, which this skill treats as an anti-pattern for a small single-package app, so for generating DTCG tokens in three tiers the design-tokens skill fits.
- Reading colors, type and spacing from a public website, since the skill structures a Flutter design system with ThemeExtension and ColorScheme, so for writing a site's values as starter tokens the extract-design-system skill fits.
- Web projects that theme with CSS variables, since the skill covers Flutter ThemeData and ThemeExtension, so for turning one request into tokens, components and dark mode theming the design-system-starter skill fits.
How to install Design System Structure Skill: Flutter Tokens, Theme and Shapes
npx skills add zakariaf/Flutter-SkillsRun the install command
Run the command above in your project to install the Flutter skills into your AI coding agent.
Open a Flutter task
Ask your agent to create or edit a ThemeData, ThemeExtension or ColorScheme, or to add a design token.
Run the scripts
Run scripts/check_raw_values.sh and scripts/check_font_bundling.sh before a PR.
Check that it loaded
Ask your agent to add a new color token to your Flutter theme. Expect a new slot in the theme extension instead of a raw color in a widget.
Key features
- No raw values gateA Color literal, Colors.*, Curves.*, Duration, BorderRadius.circular or fontSize outside lib/theme fails scripts/check_raw_values.sh, and a new need becomes a new token slot.
- Two token tiersPrimitives are named by measured value and semantic slots by role, and widgets read only the semantic tier.
- ThemeExtension with an asserting of()Tokens are read through a ThemeExtension, and of(context) asserts on a missing extension instead of using a fallback.
- Hand authored ColorSchemeThe skill rejects ColorScheme.fromSeed and dynamic_color for identity, states every role you consume and keeps the M3 role names.
- Light and dark by handDark is never an auto flip. Each theme passes AA independently, and every extension attaches to both ThemeData objects.
- Honest lerp and copyWithColors and doubles interpolate, non interpolable values snap at t below 0.5, and copyWith is mandatory.
- Reduced motion to zeroThe flag is read with MediaQuery.disableAnimationsOf and resolves to Duration.zero, never a shorter duration or a softer curve.
- Theme restored before first paintThe saved theme mode loads before runApp, and an unknown or corrupt stored value falls back explicitly.
- Bundled fontsFonts are declared in pubspec.yaml, licenses register through LicenseRegistry, weight is driven by FontWeight instead of a redundant FontVariation('wght'), and google_fonts is never used at runtime.
- Color derived lastColor is computed from a canonical value object through a semantic slot, and it is never the only channel for a status.
Frequently asked questions
What is the design system structure skill?
It is a skill that structures a Flutter design system as tokens, then theme, then modifiers, then shapes. It owns how tokens, themes, components and shapes are structured and consumed, and it leaves the choice of colors and radii to your design source of truth, so an AI coding agent keeps every aesthetic value in one directory.
How do I install the design system structure skill?
Run npx skills add zakariaf/Flutter-Skills in your project. The command installs the Flutter skills into your agent, and the design-system-structure skill is one of them. Claude Code users can also run /plugin marketplace add zakariaf/Flutter-Skills and then /plugin install flutter@flutter-skills.
What does the no raw values gate check?
A Color literal, Colors.* except transparent, Curves.*, Duration with milliseconds or seconds except Duration.zero, a literal BorderRadius.circular and fontSize in feature or shared UI code all fail scripts/check_raw_values.sh. A legitimate new need becomes a new token slot instead of an ignore comment.
Why does the skill reject ColorScheme.fromSeed?
The overrides of fromSeed do not propagate. If you override surface, surfaceContainerHigh stays seed derived. The skill hand authors the ColorScheme, states every role you consume, keeps the M3 role names so Material widgets theme themselves, and lets unstated roles take the defaults of ColorScheme.
How does the skill handle reduced motion?
It reads MediaQuery.disableAnimationsOf and resolves to Duration.zero or a cross fade to the end state. It never picks a shorter duration or a softer curve, because a user who asked the OS to stop animations asked for stop. NoSplash alone is not enough, since the pressed highlight fade is separate.
Which AI coding agents can use the skill?
The repository builds on the Agent Skills open standard, so the same files work in Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf, Cline, OpenCode and 70+ more tools. The skill is token agnostic, so the choice of colors and radii stays with your design source of truth.