color-system.skill
PK !\�p�
� � color-system/evals/routing.yamleSK��@����⒅��\JK=,=��X�E��H�$������n�fF�^�y��u�{�xz h`�r`�&Y�����o,�O�%��b�2y�o{�J�`��6�så���C�!���Zd��!t&���!�"23E�R����3����
:`�l���Ш� ��$ŸU5[fx<��|<|�������()�
�Mzq>{���hUX��2��Y9ÅdT�����OɆ�n���З`�b�+[3�UA�C�������Ȓ��L��y)�X���~)�!-�kīh
��o�f���e�
����&���64��Pƹy�s[��9�\Ɵe��:đp�(�/>}<��Z�y0�� ����*&��E��6��F%�r����
Q��Ҕ�OrR�פ���o�J|���d� s�d�=C�W�*j2h+�|��o��<�t$��nTƚo۶��Hnw�0Qt��W�MƉ��g����cP2��1ԭr�!f���-m�R5�PK !\�!� u color-system/SKILL.md�X�n#�}��(��@,Y�/��b��26V36,���
DuSjƭ�ɶ� ���|IN�}�=;؇"�u�ź�:�^��J�Z�)H�T���X�n�t�gc:�F�*��ZeV�ɘ~赈�s��� J�L(TZ��TbS<�RĔ�XZ�
,��}�|6�������
�@�4��Y���>�X>
փD�Mdb�����a�E���d�Z$V��B������ܔL�Ǧ����퓷vv�,Ւn#�&͢MkB�N�ܟ�o�IJR��+؎K�Z�˓�AD�T��%�R<�ZYI�|�x�O�:��� 8�F8�8�@ �Z&�;���ɤK�$`��A��͵�ӵ�U�(ub��jv�ix�L��"�x���"�:����X�"�HcKc�Z�`��3S�B%�~���,c�2��uP��$F�KCO�Finq҄��=��Dh�z��?�"<;tԛY����X"<챙��E�R�����9���#I��{%5ݳ�h�pUkاn�E��+��+7��YG=꺕��!N��V�5����w�~q.MNj��zǃ��vߟ�.O��471�{�.�oF�y�>I��#d�5r������+γu�&�;\Ѱh4�Y
g;�)\q���ش�u/ɣ0cz���UFu�D�"�c3�ޔ2�i:���paX��fHʛ2v[^ɭ����r��my�:|8�m��E�3���8=��Пi ���H�����s�!s�����lJ�BŦ
)?A��(/N_�)CZ�F�q�D�ݫw'��E��\�!���p��+�8_�D$($�įg��գ#,��^�Sj��.1�"�)�����Fej���!(2 Iu��n�v�=O� jO錮:�N����.�k�qZ���Kh8�u���˟E:��L�N<^�,��A��MC��ůp\��b>��_��]�=<)�v��)���A�E�n��ǃ� �\({<�N��/�A(أ0}J����9�̽� ���9t�����iV�� Noj|�הS�H�h����u�� ����y��Xk�<�JP���9 }������K�A]���(�J��+��\���{w��Ԧ�s,�k�ݲ�y�n�F��
�,��=��|LE�
��h��ht����Ú�)�Wj�P��ۊN_*B���n��P�hK�h���~vI��I�Z���h�n�8��q�>wC%�t��Uꁜ��}cɝ���;�p�Β[,�� �#�MD�z�1�������^��o��� �(T��e8z�6GV>[ϙB��w���Ǎ'b(�)�)�y���������k]1G�V3s����h(�InQ��Fg�)���¹N,j=�V��Y.��
,�؍i��S�N�ņv�dkbc����p�!�h�Tc�p��Ųse�6 �)<^ b@��;�w-��3@ 8bq���3�ƒeU�pFDFj�M�Gk�BQs(�⪈)�+@����X���H��_V�������6}n��s�%���TÜq�8�.}.�*Q�����wZ��|��Z]z��}�3�w7�?��_�|�������2���H�7?^|����%��}�{�j�u
V�hƙ��_�pנ��ԑJ�ȞrA{�D�V8�f��~[R^����+B'
��o ���FK���?��K�[Z�\�N���c����#�p�J�aB����v��_
yCQ*`PO���,rP䱭��-zZo^ i�0���}�K.����+�ېZ�V:�R���"�!O"��� �-�a!����㴕�:;
�/�#|[�'�%�v�'�g������-�vCU�N��@���/���ǤI�����w���vj/��������W@����p 9k������3�%�����mk�^�i�yq�D/bٹ��`�؞��(�~�U�s!��"���^�w�Υ��7+��#a1f���� U�{ѐ�t�s�>s��K�۩��!7��i�s�o=�I�ow'M��~8!a3w9C���y�1�DMµlY��x#N���Q�d<tc����<��
1��滛[3�Ʊ�ѫ� ��M^1f��/�k�A�rwzg���p�[Q�G�~���}�_�\�j}�-����p���Jq���k���6j*���ꖤ�1C����C]=F�L�]�������T;��T�����ё���E�.�ٯxR��d�䁷�Z�5g �cv�f��T�S̸P�r�$8�PLq��<��w�I���
@���J>���e����gl,2w~��������y�b��$�N���
�R3�����K>Y����J�t�e��y3���:��ѡc)��v}��_�W�Ԝf��_��8��o�"��"s�Τ�G,'PF]���z�}7Q��Q7)x��)����P��?��� PK !\�p�
� � � color-system/evals/routing.yamlPK !\�!� u �7 color-system/SKILL.mdPK � � evals/routing.yaml
should_fire:
- 'build a semantic color token system: surface-primary, text-muted, border-subtle'
- 'design an accessible dark mode palette that avoids pure #000000 black surfaces'
- 'generate 10-step perceptual color scales (50 to 950) using OKLCH color space'
- 'map semantic tokens to light and dark theme modes with consistent contrast'
- 'define functional color palettes for success, warning, destructive, and info states'
- 'structure color design tokens in Figma and export them as CSS variables'
- 'ensure all text and background token pairings achieve minimum 4.5:1 contrast'
- 'organize brand colors vs neutral surface colors in our design system'
should_not_fire:
- prompt: 'explore emotional and psychological associations of colors'
expect: 'color-psychology'
- prompt: 'audit UI screens for accessibility contrast violations'
expect: 'accessibility-review'
- prompt: 'build full UI component libraries in Figma'
expect: 'component-library'
SKILL.md
---
name: color-system
group: Design system
description: >-
Turn a chosen direction into a real palette: tints, WCAG contrast, dark mode mapping, elevation
and tokens. Use when building semantic color tokens, dark mode palettes, or contrast scales.
---
# color-system
## Core Philosophy
A production color system is not a static Figma swatch board of 5 favorite hex codes. A true color system is a mathematically coherent, tokenized software architecture. It governs contrast ratios, elevation surface ramps, perceptual lightness distribution, semantic state bindings, and flawless bidirectional light/dark mode transitions without manual per-screen overrides.
---
## 4-Step Scalable Color System Engineering
### Step 1: The 3-Tier Token Architecture
1. **The Token Hierarchy**:
- *Tier 1: Global Primitives (Raw Values)*:
- `blue-500: #3B82F6`, `slate-900: #0F172A`. Never consume primitives directly in components.
- *Tier 2: Semantic Tokens (System Purpose)*:
- `surface-canvas: var(--slate-900)`, `action-primary: var(--blue-500)`.
- *Tier 3: Component Tokens (Scoped Overrides)*:
- `button-primary-bg: var(--action-primary)`.
### Step 2: Perceptual Color Spaces (OKLCH) & Shade Generation
1. **Why sRGB/HSL Fails**:
- HSL is mathematically flawed: pure yellow ($H=60$) has vastly higher perceived luminance than pure blue ($H=240$), making consistent lightness across hues impossible.
2. **The OKLCH Standard**:
- Use **OKLCH** (`oklch(L C H)`):
- $L$ = Perceptual Lightness (0% to 100%).
- $C$ = Chroma / Saturation (0 to ~0.37).
- $H$ = Hue angle ($0^\circ$ to $360^\circ$).
- Generating consistent shades (50 to 950): Fix Hue and Chroma, and step Lightness mathematically from 95% down to 10%.
### Step 3: Elevation Ramps & Dark Mode Surface Parity
1. **The Elevation Surface Ladder in Dark Mode**:
- In light mode, elevation is communicated via drop shadows (`box-shadow`).
- In dark mode, shadows are invisible against dark backgrounds. Elevation must be communicated via **surface lightness stepping**:
- `surface-base (0dp)`: `oklch(14% 0.02 260)` (Canvas background)
- `surface-raised (1dp)`: `oklch(18% 0.02 260)` (Card background)
- `surface-overlay (4dp)`: `oklch(22% 0.02 260)` (Dropdown menu)
- `surface-modal (8dp)`: `oklch(26% 0.02 260)` (Floating dialog)
2. **Never Use Pure Black (`#000000`) for Dark Mode**:
- Pure black causes harsh pixel smearing on OLED screens and severe contrast strain against pure white text. Use deep slate/navy tints ($L pprox 12–15\%$).
### Step 4: Semantic State Mapping & Automated Contrast Gates
1. **Interactive State Offsets**:
- Hover: Adjust lightness by $\pm 5\%$ in OKLCH.
- Pressed / Active: Adjust lightness by $\pm 10\%$.
- Disabled: Lock Chroma to 0 (grayscale) and set opacity to 40%.
2. **Contrast Verification**:
- Automatically assert that every text semantic token against its assigned surface token achieves $\ge 4.5:1$ WCAG contrast.
---
## Deliverable Format: Color Tokens Definition (`tokens.css`)
```css
/* ==========================================================================
PRODUCTION COLOR SYSTEM TOKENS (OKLCH)
========================================================================== */
:root {
/* 1. Global Primitives (Indigo Scale) */
--indigo-50: oklch(96% 0.02 270);
--indigo-500: oklch(58% 0.22 270);
--indigo-600: oklch(50% 0.22 270);
--indigo-900: oklch(24% 0.12 270);
/* Slate Scale */
--slate-50: oklch(98% 0.005 250);
--slate-100: oklch(94% 0.010 250);
--slate-800: oklch(22% 0.020 250);
--slate-900: oklch(14% 0.020 250);
/* 2. Semantic Mappings (Light Mode Default) */
--surface-canvas: var(--slate-50);
--surface-card: #ffffff;
--text-primary: var(--slate-900);
--text-muted: var(--slate-800);
--border-subtle: var(--slate-100);
--action-primary-bg: var(--indigo-500);
--action-primary-hover: var(--indigo-600);
--action-primary-text: #ffffff;
}
/* 3. Dark Mode Overrides (Automatic Surface Inversion) */
[data-theme="dark"] {
--surface-canvas: var(--slate-900);
--surface-card: var(--slate-800);
--text-primary: var(--slate-50);
--text-muted: var(--slate-100);
--border-subtle: var(--slate-800);
--action-primary-bg: var(--indigo-500);
--action-primary-hover: var(--indigo-600);
--action-primary-text: #ffffff;
}
```
---
## Worked Example: Automated CI Contrast Gate
- **Tooling**: Integrated `stylelint-color-contrast` into frontend test suite.
- **Detection**: PR attempted to set secondary text to `#888888` on `#FFFFFF` (contrast 3.5:1; fails WCAG AA).
- **Resolution**: CI failed build automatically; developer adjusted token to `#6B7280` (4.6:1), maintaining full accessibility compliance.
---
## Verification Checklist
- [ ] Tokens structured into 3 distinct tiers (Primitives -> Semantics -> Components).
- [ ] Color shades generated in perceptual color space (OKLCH or Lab).
- [ ] Dark mode surfaces use stepped elevation lightness ramps rather than pure black.
- [ ] All interactive states (Hover, Active, Focus, Disabled) mathematically derived.
- [ ] Automated tests verify $\ge 4.5:1$ contrast across all text/surface pairings.
---
## Anti-Patterns
- **Hardcoding Hex Codes in Components**: Writing `color: #4F46E5` directly inside a React component stylesheet.
- **Inverted Dark Mode Negatives**: Inverting black text to white while leaving bright background containers blindingly white.
- **Pure Black OLED Traps**: Setting `#000000` as the global background, causing severe text smearing on mobile scrolling.