agentleFS
Joyboy-dyJoyboy-dy/felicio-ai-skills/skills/chromatic-design/SKILL.md

chromatic-design

Skill0 starsChanged 3 months agoMITView on GitHub

Use when designing, extending, migrating, or auditing an interface color system: semantic tokens, palettes, light/dark themes, accessible foreground/background pairs, contrast, color roles, or CSS/Tailwind color usage.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 11 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do not use this as a general visual redesign skill.

    line 14
  2. Distinctive:

    Never assume OKLCH, HSL, hex, CSS variables, Tailwind, a component library, or any token naming convention.

    line 18
  3. Distinctive:

    Run the bundled scanner when a quick inventory is useful:

    line 36
  4. Distinctive:

    Treat scanner output as candidates to inspect, not proof that a literal is wrong.

    line 42
  5. Distinctive:

    Use the project's accessibility target.

    line 68
  6. Very specific:

    Read references/wcag-formulas.md when exact luminance/contrast math or thresholds are relevant.

    line 76
  7. Distinctive:

    Prefer changing semantic tokens over scattering new literals through components.

    line 80
  8. Very specific:

    Run the repository's real typecheck/lint/tests/build when code was changed.

    line 94
  9. Distinctive:

    When the user explicitly asks to migrate a color system:

    line 98
  10. Distinctive:

    avoid mixing two token systems indefinitely.

    line 103
  11. Distinctive:

    update documentation/examples in the same change.

    line 104
  12. Distinctive:

    verify both themes and high-risk states after migration.

    line 105
  13. Distinctive:

    If migration is not requested, do not turn maintenance into a color-system rewrite.

    line 107
  14. Distinctive:

    When reporting color work, state:

    line 121

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Chromatic Design

Build and maintain color systems that are coherent, accessible, and compatible with the project's existing styling architecture.

Use when

Activate for requests involving palette creation, semantic color tokens, theme pairing, dark mode, contrast, brand-to-UI color translation, color migrations, or inconsistent raw color usage.

Do not use this as a general visual redesign skill. Hand typography, layout, composition, and art direction to frontend-aesthetics; use ux-ui-audit when the primary request is an evidence-based audit of an existing interface.

Core rule: inspect before changing color syntax

Never assume OKLCH, HSL, hex, CSS variables, Tailwind, a component library, or any token naming convention. First inspect the repository and preserve its established representation unless the user explicitly asks for a migration or a new system is being created.

For new systems, prefer a perceptually useful color space such as OKLCH when the target browser/toolchain supports it. For existing systems, consistency and safe migration matter more than changing syntax for its own sake.

Workflow

1. Discover the current system

Inspect the files that actually define or consume colors:

  • global styles and theme files;
  • framework/config files that extend colors;
  • component-library theme variables;
  • design-token files;
  • utility classes and CSS modules;
  • SVG/icon color handling;
  • light/dark or multi-theme selectors.

Run the bundled scanner when a quick inventory is useful:

python scripts/color_tools.py scan <project-root> --json

Treat scanner output as candidates to inspect, not proof that a literal is wrong.

2. Map semantic roles before choosing values

Separate roles from values. Typical roles include:

  • page/background and foreground;
  • elevated/card/popover surfaces;
  • muted/subtle surfaces and text;
  • borders, dividers, focus rings;
  • primary/secondary/accent actions;
  • destructive, warning, success, informational states;
  • charts/data-series colors when applicable.

Reuse the repository's role names when they already exist. Do not create duplicate aliases that mean the same thing.

3. Define interaction-state relationships

For interactive roles, account for default, hover, active/pressed, focus-visible, disabled, selected, and visited states where applicable. State changes must remain recognizable without relying on color alone when accessibility requires another cue.

4. Pair themes deliberately

Design light and dark themes as related systems, not mechanical inversions. Verify each semantic surface against its foreground independently in every theme. Preserve hierarchy: a dark theme still needs distinct background, surface, elevated surface, muted content, and borders.

5. Validate contrast

Use the project's accessibility target. For ordinary WCAG AA checks, evaluate text/background and meaningful UI boundaries separately. Do not infer compliance from visual appearance.

The helper can calculate a WCAG contrast ratio for opaque sRGB colors:

python scripts/color_tools.py contrast '#0a0a0a' '#ffffff'

Read references/wcag-formulas.md when exact luminance/contrast math or thresholds are relevant. Read references/color-models.md when selecting or converting color spaces.

6. Apply the smallest coherent change

Prefer changing semantic tokens over scattering new literals through components. Preserve public token names when possible. If a token rename or color-space migration is required, enumerate consumers and migrate them as one controlled change.

7. Validate in context

Check at minimum:

  • all supported themes;
  • normal/hover/focus/disabled/selected/error states;
  • small text and subdued text;
  • borders/focus rings against adjacent surfaces;
  • destructive/success/warning information without color-only meaning;
  • charts/legends if changed;
  • screenshots or real rendered UI when available.

Run the repository's real typecheck/lint/tests/build when code was changed. Do not claim contrast or theme correctness from a static token scan alone.

Migration rules

When the user explicitly asks to migrate a color system:

  1. inventory existing definitions and consumers;
  2. define old-role → new-role mapping before editing;
  3. preserve semantics even when numeric values change;
  4. avoid mixing two token systems indefinitely;
  5. update documentation/examples in the same change;
  6. verify both themes and high-risk states after migration.

If migration is not requested, do not turn maintenance into a color-system rewrite.

Common failure modes

  • Hard-coding brand colors directly into many components instead of assigning semantic roles.
  • Treating dark mode as invert() or a value-by-value inversion.
  • Checking only primary text while muted text, placeholder text, borders, and focus states fail.
  • Introducing a new color syntax simply because it is newer.
  • Using opacity over unknown backgrounds and calculating contrast against the wrong composited color.
  • Declaring a palette accessible without evaluating actual foreground/background pairs.
  • Removing existing aliases without finding all consumers.

Output

When reporting color work, state:

  1. the detected color architecture and theme mechanism;
  2. the semantic roles affected;
  3. exact changes or recommendations;
  4. contrast results for pairs actually calculated;
  5. states/themes validated;
  6. remaining uncertainties requiring rendered inspection.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.