@greenharness/greenrack-cli 0.0.0-reserved → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +334 -1
  2. package/agents/design-system-lookup.md +59 -0
  3. package/dist/bin.d.ts +3 -0
  4. package/dist/bin.d.ts.map +1 -0
  5. package/dist/bin.js +145 -0
  6. package/dist/bin.js.map +1 -0
  7. package/dist/catalog.d.ts +13 -0
  8. package/dist/catalog.d.ts.map +1 -0
  9. package/dist/catalog.js +67 -0
  10. package/dist/catalog.js.map +1 -0
  11. package/dist/commands/context.d.ts +17 -0
  12. package/dist/commands/context.d.ts.map +1 -0
  13. package/dist/commands/context.js +110 -0
  14. package/dist/commands/context.js.map +1 -0
  15. package/dist/commands/doctor.d.ts +75 -0
  16. package/dist/commands/doctor.d.ts.map +1 -0
  17. package/dist/commands/doctor.js +1008 -0
  18. package/dist/commands/doctor.js.map +1 -0
  19. package/dist/commands/hook.d.ts +10 -0
  20. package/dist/commands/hook.d.ts.map +1 -0
  21. package/dist/commands/hook.js +323 -0
  22. package/dist/commands/hook.js.map +1 -0
  23. package/dist/commands/list.d.ts +4 -0
  24. package/dist/commands/list.d.ts.map +1 -0
  25. package/dist/commands/list.js +59 -0
  26. package/dist/commands/list.js.map +1 -0
  27. package/dist/commands/lookup.d.ts +13 -0
  28. package/dist/commands/lookup.d.ts.map +1 -0
  29. package/dist/commands/lookup.js +66 -0
  30. package/dist/commands/lookup.js.map +1 -0
  31. package/dist/commands/manifest.d.ts +5 -0
  32. package/dist/commands/manifest.d.ts.map +1 -0
  33. package/dist/commands/manifest.js +33 -0
  34. package/dist/commands/manifest.js.map +1 -0
  35. package/dist/commands/mcp.d.ts +159 -0
  36. package/dist/commands/mcp.d.ts.map +1 -0
  37. package/dist/commands/mcp.js +235 -0
  38. package/dist/commands/mcp.js.map +1 -0
  39. package/dist/commands/mockup.d.ts +80 -0
  40. package/dist/commands/mockup.d.ts.map +1 -0
  41. package/dist/commands/mockup.js +714 -0
  42. package/dist/commands/mockup.js.map +1 -0
  43. package/dist/commands/skill.d.ts +15 -0
  44. package/dist/commands/skill.d.ts.map +1 -0
  45. package/dist/commands/skill.js +398 -0
  46. package/dist/commands/skill.js.map +1 -0
  47. package/dist/disambiguation.d.ts +24 -0
  48. package/dist/disambiguation.d.ts.map +1 -0
  49. package/dist/disambiguation.js +56 -0
  50. package/dist/disambiguation.js.map +1 -0
  51. package/dist/extension-pointer.d.ts +7 -0
  52. package/dist/extension-pointer.d.ts.map +1 -0
  53. package/dist/extension-pointer.js +30 -0
  54. package/dist/extension-pointer.js.map +1 -0
  55. package/dist/format.d.ts +19 -0
  56. package/dist/format.d.ts.map +1 -0
  57. package/dist/format.js +213 -0
  58. package/dist/format.js.map +1 -0
  59. package/dist/hook-script.d.ts +73 -0
  60. package/dist/hook-script.d.ts.map +1 -0
  61. package/dist/hook-script.js +165 -0
  62. package/dist/hook-script.js.map +1 -0
  63. package/dist/index.d.ts +7 -0
  64. package/dist/index.d.ts.map +1 -0
  65. package/dist/index.js +6 -0
  66. package/dist/index.js.map +1 -0
  67. package/dist/legacy-names.d.ts +26 -0
  68. package/dist/legacy-names.d.ts.map +1 -0
  69. package/dist/legacy-names.js +26 -0
  70. package/dist/legacy-names.js.map +1 -0
  71. package/dist/manifest.d.ts +51 -0
  72. package/dist/manifest.d.ts.map +1 -0
  73. package/dist/manifest.js +229 -0
  74. package/dist/manifest.js.map +1 -0
  75. package/dist/registry-types.d.ts +106 -0
  76. package/dist/registry-types.d.ts.map +1 -0
  77. package/dist/registry-types.js +2 -0
  78. package/dist/registry-types.js.map +1 -0
  79. package/dist/registry.d.ts +52 -0
  80. package/dist/registry.d.ts.map +1 -0
  81. package/dist/registry.js +95 -0
  82. package/dist/registry.js.map +1 -0
  83. package/dist/scan.d.ts +19 -0
  84. package/dist/scan.d.ts.map +1 -0
  85. package/dist/scan.js +29 -0
  86. package/dist/scan.js.map +1 -0
  87. package/dist/search.d.ts +16 -0
  88. package/dist/search.d.ts.map +1 -0
  89. package/dist/search.js +75 -0
  90. package/dist/search.js.map +1 -0
  91. package/dist/skill-template.d.ts +24 -0
  92. package/dist/skill-template.d.ts.map +1 -0
  93. package/dist/skill-template.js +140 -0
  94. package/dist/skill-template.js.map +1 -0
  95. package/greenharness.toml +38 -0
  96. package/package.json +76 -4
  97. package/registry.json +12893 -0
  98. package/skills/colors/LICENSE +21 -0
  99. package/skills/colors/NOTICE.md +36 -0
  100. package/skills/colors/SKILL.md +101 -0
  101. package/skills/colors/color-formats.md +90 -0
  102. package/skills/colors/color-usage.md +109 -0
  103. package/skills/colors/contrast.md +70 -0
  104. package/skills/colors/palette-generation.md +108 -0
  105. package/skills/colors/palette-structure.md +72 -0
  106. package/skills/colors/token-naming.md +99 -0
  107. package/skills/greenrack-mockup/SKILL.md +115 -0
  108. package/skills/typography/LICENSE +21 -0
  109. package/skills/typography/NOTICE.md +36 -0
  110. package/skills/typography/SKILL.md +171 -0
  111. package/skills/typography/choosing-fonts.md +53 -0
  112. package/skills/typography/css-cheat-sheet.md +67 -0
  113. package/skills/typography/details-and-accessibility.md +84 -0
  114. package/skills/typography/spacing-and-sizing.md +87 -0
  115. package/skills/typography/variable-fonts-and-opentype.md +100 -0
  116. package/skills/typography/wrapping-and-punctuation.md +23 -0
  117. package/skills/ui/LICENSE +21 -0
  118. package/skills/ui/NOTICE.md +38 -0
  119. package/skills/ui/SKILL.md +141 -0
  120. package/skills/ui/animations.md +170 -0
  121. package/skills/ui/enter-exit.md +157 -0
  122. package/skills/ui/icon-transitions.md +72 -0
  123. package/skills/ui/icons.md +105 -0
  124. package/skills/ui/performance.md +63 -0
  125. package/skills/ui/surfaces.md +166 -0
@@ -0,0 +1,87 @@
1
+ # Spacing and sizing
2
+
3
+ Units, a starting type scale, the heading mapping, line-height for wrapping text and text trimming.
4
+
5
+ ## Units
6
+
7
+ | Unit | Behavior |
8
+ | --- | --- |
9
+ | `px` | Fixed |
10
+ | `em` | Scales with the current font size |
11
+ | `rem` | Scales with the root font size |
12
+ | `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
13
+
14
+ ## Type scale
15
+
16
+ Pick an existing scale or define one. Tailwind's `text-xs` through `text-9xl`, each pairing a size with a line height, is a solid ready-made choice.
17
+
18
+ A starting point for a product interface, named by role:
19
+
20
+ ```css
21
+ :root {
22
+ --text-caption: 0.8125rem;
23
+ --text-body: 1rem;
24
+ --text-heading: 1.125rem;
25
+ --text-title: 1.5rem;
26
+ --text-display: 2.25rem;
27
+ }
28
+ ```
29
+
30
+ | Role | Size | Line-height | Weight |
31
+ | --- | --- | --- | --- |
32
+ | Display | `2.25rem` (36px) | `1.1` | `600` |
33
+ | Title | `1.5rem` (24px) | `1.2` | `600` |
34
+ | Heading | `1.125rem` (18px) | `1.3` | `600` |
35
+ | Body | `1rem` (16px) | `1.5` | `400` |
36
+ | Caption | `0.8125rem` (13px) | `1.4` | `400` |
37
+
38
+ Emphasis within a role is one weight step up (`400` → `500`), not a size change.
39
+
40
+ ## Heading hierarchy
41
+
42
+ ```css
43
+ h1 { font-size: var(--text-display); }
44
+ h2 { font-size: var(--text-title); }
45
+ h3 { font-size: var(--text-heading); }
46
+ ```
47
+
48
+ In Tailwind, centralize the per-level classes in a component or `@layer base` rather than repeating them inline.
49
+
50
+ ## Line-height for wrapping text
51
+
52
+ ```css
53
+ /* Bad: card description at heading leading */
54
+ .card-description { line-height: 1.1; }
55
+
56
+ /* Good: it wraps to 3 lines, so it reads as body text */
57
+ .card-description { line-height: 1.4; }
58
+ ```
59
+
60
+ ## Text trimming with text-box
61
+
62
+ `text-box` takes which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
63
+
64
+ | Keyword | Trims at |
65
+ | --- | --- |
66
+ | `cap` | The cap height (top) |
67
+ | `alphabetic` | The baseline (bottom) |
68
+ | `text` | The font's own text edge, keeping room for descenders |
69
+
70
+ ```css
71
+ /* trim top and bottom */
72
+ .badge {
73
+ text-box: trim-both cap alphabetic;
74
+ }
75
+
76
+ /* trim only the top */
77
+ .heading {
78
+ text-box: trim-start cap;
79
+ }
80
+
81
+ /* trim only the bottom */
82
+ .label {
83
+ text-box: trim-end alphabetic;
84
+ }
85
+ ```
86
+
87
+ Supported in Chromium 133+ and Safari 18.2+, not yet Firefox. Unsupported browsers keep the default leading.
@@ -0,0 +1,100 @@
1
+ # Variable fonts and OpenType
2
+
3
+ What a font file can do beyond drawing letters and how to reach those abilities from CSS.
4
+
5
+ ## Static vs variable
6
+
7
+ - **Static font:** one weight and one style per file. Regular, medium and bold is three files.
8
+ - **Variable font:** a whole range in one file. Any value in it works, such as `font-weight: 589`.
9
+
10
+ A variable font is not automatically better. At one or two weights, static files can be smaller. At several weights, optical sizes or custom axes, a variable font usually wins.
11
+
12
+ ## Disable synthesis narrowly
13
+
14
+ `font-synthesis: none` disables weight, style, small-cap and position synthesis together. Scope it to an isolated treatment you have verified across the fallback stack:
15
+
16
+ ```css
17
+ .brand-wordmark {
18
+ font-synthesis: none;
19
+ }
20
+ ```
21
+
22
+ To disable one mode, use its longhand: `font-synthesis-weight`, `font-synthesis-style`, `font-synthesis-small-caps` or `font-synthesis-position`.
23
+
24
+ ## Axes
25
+
26
+ Variable-font controls, each with a four-letter tag. A font supports only the axes its designer included.
27
+
28
+ | Axis | Tag | Controls |
29
+ | --- | --- | --- |
30
+ | Weight | `wght` | Stroke thickness (like `font-weight`) |
31
+ | Optical size | `opsz` | Details and spacing tuned for the display size |
32
+ | Width | `wdth` | Glyph width |
33
+ | Slant | `slnt` | Slant angle |
34
+ | Custom | e.g. `GRAD` (Roboto Flex) | Whatever the designer built |
35
+
36
+ Inter's variable file exposes only `wght` and `opsz`.
37
+
38
+ Optical sizes predate variable fonts. Many families still ship them as separate `Text` and `Display` files instead of an `opsz` axis.
39
+
40
+ ## Raw tags only for custom axes
41
+
42
+ `font-variation-settings` silently does nothing on a non-variable fallback, where `font-weight` still picks the nearest face:
43
+
44
+ ```css
45
+ /* Good: common axes use the properties */
46
+ .heading {
47
+ font-weight: 650;
48
+ }
49
+
50
+ /* Good: custom axis with no property of its own */
51
+ .heading-grade {
52
+ font-variation-settings: "GRAD" 80;
53
+ }
54
+
55
+ /* Bad: weight via raw tag breaks on fallback fonts */
56
+ .heading {
57
+ font-variation-settings: "wght" 650;
58
+ }
59
+ ```
60
+
61
+ ## OpenType features
62
+
63
+ Unlike axes, features work the same on static and variable fonts. A font ships only the features its designer included.
64
+
65
+ | Tag | Feature |
66
+ | --- | --- |
67
+ | `tnum` | Tabular numbers: every digit the same width |
68
+ | `zero` | Slashed zero: `0` distinct from `O` |
69
+ | `liga` | Ligatures: joins pairs like "fi" into one shape |
70
+ | `ss01`–`ss20` | Stylistic sets (numbered slots) |
71
+ | `cv01`–`cv99` | Character variants (numbered slots) |
72
+
73
+ Common features have a `font-variant-*` property, and `font-feature-settings` is for the rest:
74
+
75
+ ```css
76
+ /* Good: common features use the properties */
77
+ .price {
78
+ font-variant-numeric: tabular-nums;
79
+ }
80
+
81
+ .id {
82
+ font-variant-numeric: slashed-zero;
83
+ }
84
+
85
+ /* Good: niche feature with no property of its own */
86
+ .logo {
87
+ font-feature-settings: "ss01" 1;
88
+ }
89
+ ```
90
+
91
+ ## Small caps, superscripts, subscripts
92
+
93
+ - **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
94
+ - **Superscripts** sit above the normal line, the 2 in x², and **subscripts** below it, as in H₂O. Enable proper glyphs with `font-variant-position`.
95
+
96
+ Both require the font to include the glyphs.
97
+
98
+ ## Stylistic sets and character variants
99
+
100
+ `ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.
@@ -0,0 +1,23 @@
1
+ # Wrapping and punctuation
2
+
3
+ Line length, typographic characters and mixed-direction text.
4
+
5
+ ## Measure (line length)
6
+
7
+ Any unit works. `65ch` measures characters directly, one `ch` being the width of the `0` in the current font, and a pixel or rem cap is just as good. At a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font. Tailwind's `max-w-xl` (`576px`), `max-w-2xl` (`672px`) and `max-w-prose` (`65ch`) all fit. Recheck the cap if the body font size changes.
8
+
9
+ ## Smart punctuation
10
+
11
+ | Instead of | Use |
12
+ | --- | --- |
13
+ | Straight quotes `"..."` | Curly quotes that curve around the text (keep straight quotes in code) |
14
+ | Hyphen in ranges | En dash: `2010–2020` |
15
+ | Two hyphens for an aside | Em dash character |
16
+ | Three periods `...` | The single ellipsis character `…` |
17
+ | Regular space in `10 km` | ` ` so the value never breaks apart |
18
+ | Uncontrolled word breaks | `­` to mark where a word may break, or `hyphens: auto` with the correct `lang` |
19
+
20
+ ## Internationalization
21
+
22
+ - **Long paragraphs align by their own language.** A one- or two-line snippet follows the surrounding UI's direction. A paragraph of three or more lines aligns to its own script instead, so an English paragraph stays start-aligned LTR even inside an RTL interface. `text-align: start` with the correct `lang` and `dir` on the paragraph element handles this.
23
+ - **Digits keep their order.** A phone number or "541" reads identically in RTL, because the Unicode bidi algorithm keeps digit runs left to right. `<bdi>` repairs a value whose order adjacent RTL text disturbs.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jakub Krehel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,38 @@
1
+ # Notice
2
+
3
+ This skill is a fork of `better-ui/` from the repository `jakubkrehel/skills`, at commit `4c66b1fa86e9ab70187b43d7da9b6fdb29f2ef63`, fetched 2026-10-16.
4
+
5
+ Local edits:
6
+
7
+ - Renamed by `scripts/fork-interface-skills.sh` at dotfiles commit `5fbdc4b` (`better-ui` to `ui`).
8
+ - Dropped `agents/openai.yaml`.
9
+ - Added the precedence block after the introduction of `SKILL.md`.
10
+ - Reconciled the clause in `ui/SKILL.md` that limited project tokens, so a project token always wins.
11
+ - Extended the `description:` with animation triggers (menu or dialog enter and exit, staggered items, hover and press feedback, icon swaps), so `ui` wins those prompts over `motion-design`: 18/18 should, 0/12 near-miss on 2026-10-17, against 12/18 before.
12
+ - Replaced the line calling the untokenised ui values known gaps (issue #120) with one naming them as greenrack tokens: `duration.slower`, `duration.stagger`, `easing.emphasized`.
13
+
14
+ Updating: diff upstream from the pinned commit, have a frontier model port the changes over the local edits, then bump the pin.
15
+
16
+ The upstream license (MIT) applies; the text is in `LICENSE`:
17
+
18
+ > MIT License
19
+ >
20
+ > Copyright (c) 2026 Jakub Krehel
21
+ >
22
+ > Permission is hereby granted, free of charge, to any person obtaining a copy
23
+ > of this software and associated documentation files (the "Software"), to deal
24
+ > in the Software without restriction, including without limitation the rights
25
+ > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
26
+ > copies of the Software, and to permit persons to whom the Software is
27
+ > furnished to do so, subject to the following conditions:
28
+ >
29
+ > The above copyright notice and this permission notice shall be included in all
30
+ > copies or substantial portions of the Software.
31
+ >
32
+ > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
33
+ > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
34
+ > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
35
+ > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
36
+ > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
37
+ > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
38
+ > SOFTWARE.
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: ui
3
+ description: Polishes the surfaces, icons and motion in your project with exact values for border radius, optical alignment, shadows, icon states and animation. Use when adding or tuning a UI animation or transition, such as a menu or dialog enter and exit, staggered list items, hover and press feedback or an icon swap.
4
+ ---
5
+
6
+ **Gate.** This skill applies only in a repository whose `package.json` depends on `@greenharness/greenrack-ui`, or on the old `@duro-app/ui` it replaces (a `workspace:` dependency counts). Anywhere else, stop: do not apply it.
7
+
8
+ # UI polish
9
+
10
+ This skill holds the visual polish for surfaces, icons and motion, with the exact value each detail takes. It applies once the underlying interaction is sound, and a polish finding never outranks a broken interaction.
11
+
12
+ A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal.
13
+
14
+ Where greenrack defines the value, these win: the `spacing.css.ts` radii, `shadows.css.ts` and `motion.css.ts`.
15
+
16
+ The ui values `300ms` enter, `100ms` stagger and `cubic-bezier(0.2, 0, 0, 1)` are greenrack tokens (`duration.slower`, `duration.stagger`, `easing.emphasized`) that a review uses instead of the literal.
17
+
18
+ ## Exact values, optional polish
19
+
20
+ The values below are exact, not ranges to approximate. `cubic-bezier(0.2, 0, 0, 1)` is not `cubic-bezier(0.4, 0, 0.2, 1)`, and `0.96` is not `0.95`. The optical nudges and the concentric padding cutoff are the exceptions. They are starting points, judged by eye.
21
+
22
+ Keep the project's component library, tokens and density. A project token always wins over a value here, and this skill's value applies only where the project has no token for it. Match the project's motion language wherever no rule here gives a value. A deliberate and consistent project convention, such as a style with no shadows, is a preference and not a finding. The same detail done two ways within the project is a finding.
23
+
24
+ Text wrapping, font rendering, tabular numbers and text spacing belong to `typography`. Hit areas, keyboard support, ARIA and the reduced-motion requirement belong to `accessibility`. Grouping, section spacing, breakpoints and spatial RTL belong to `layout`, except directional icon mirroring. Color tokens and contrast measurement belong to `colors`.
25
+
26
+ ## Outer radius equals inner radius plus padding
27
+
28
+ Where nested surfaces share a visible, even inset, the outer radius is the inner radius plus the padding plus any border width. Past `24px` of padding, or where the padding is deliberately asymmetric, treat the layers as separate surfaces and keep each one's radius token. Recipes are in [surfaces.md](surfaces.md).
29
+
30
+ ## Align optically where geometry looks off
31
+
32
+ Where geometric centering looks off, nudge by eye. Give a button `2px` less padding on its icon side, shift a play triangle toward its point and fix asymmetric glyphs in the SVG itself. Recipes are in [surfaces.md](surfaces.md#optical-alignment).
33
+
34
+ ## Shadows for elevation, borders for structure
35
+
36
+ Where a border exists only to create depth, replace it with layered transparent `box-shadow` values. Keep borders on dividers, separators, table cells and selected states. Keep them on form inputs too, whose boundary needs 3:1 non-text contrast under `accessibility`. Focus rings belong to `accessibility` as well.
37
+
38
+ Forced-colors mode removes every `box-shadow`. Keep `border: 1px solid transparent` under a shadow ring so that mode still draws an edge. Recipes are in [surfaces.md](surfaces.md#shadow-recipes).
39
+
40
+ ## Outline images in pure black or white
41
+
42
+ Give content images a `1px` outline inset by `1px`. Use `oklch(0 0 0 / 0.1)` in light mode and `oklch(1 0 0 / 0.1)` in dark. Never use a palette near-black, a tinted neutral or the accent color, because the tint shows as a colored fringe on the image edge. Skip transparent artwork such as logos and illustrations. The recipe is in [surfaces.md](surfaces.md#image-outlines).
43
+
44
+ ## Transitions, not keyframes, for interactive state
45
+
46
+ Drive interactive state changes with CSS transitions or a motion library's springs, which retarget when the user reverses mid-flight. Keyframes run a fixed timeline and cannot reverse, so reserve them for sequences that run once. See [animations.md](animations.md).
47
+
48
+ ## Press scales to 0.96
49
+
50
+ A pressed button scales to `0.96` over `150ms` with `ease-out`, and a disabled one never scales. Give the button an opt-out where the motion would distract, through the component's existing variant API or a `static` prop. See [recipes for CSS, Tailwind and Motion](animations.md#scale-on-press).
51
+
52
+ ## High-frequency interactions get no animation
53
+
54
+ Keystrokes, row hovers and tab switches get instant feedback, or a transition of `150ms` or less on `opacity` or `background-color`. Reserve expressive motion for infrequent moments such as a view's first load, a success state or an empty state.
55
+
56
+ Every animated state change also leaves a static cue in the form of a color, icon or label. Motion is never the only feedback channel.
57
+
58
+ ## Gate motion behind the reduced-motion preference
59
+
60
+ `accessibility` owns the requirement, and no recipe here ships without it. Run movement, scale and blur only under `prefers-reduced-motion: no-preference`. Under reduced motion, replace them with an opacity cross-fade rather than removing the element instantly. Recipes for CSS, Tailwind and Motion are in [animations.md](animations.md#reduced-motion-fallback).
61
+
62
+ ## Stagger infrequent entrances by 100ms
63
+
64
+ Where sequence communicates hierarchy in a staged entrance, split the content into semantic chunks such as title, description and actions. Stagger them `100ms` apart, each entering with opacity, `4px` of blur and `12px` of `translateY` over `300ms` with `ease-out`. Never stagger routine interactions. See [enter-exit.md](enter-exit.md).
65
+
66
+ ## Exits are shorter and smaller than enters
67
+
68
+ Exit with opacity, `4px` of blur and a fixed `-12px` `translateY` over `150ms` with `ease-out`, never the full container height. Slide fully out only where the destination carries meaning, such as a drawer closing. Remove the element instantly where motion adds no information. See [enter-exit.md](enter-exit.md#exit-animations).
69
+
70
+ ## Skip state animations on first render
71
+
72
+ Set `initial={false}` on an `AnimatePresence` that wraps a state swap, so the default state does not animate in on mount. Never set it around an intentional entrance such as a staggered hero. See [animations.md](animations.md#skip-animation-on-page-load).
73
+
74
+ ## Cross-fade contextual icons with exact values
75
+
76
+ Where an icon swaps on an infrequent state change, such as play to pause or copy to copied, cross-fade it. Scale runs `0.25` to `1`, opacity `0` to `1` and blur `4px` to `0px`. With a motion library, use `{ type: "spring", duration: 0.3, bounce: 0 }`, and bounce is always `0`. Without one, keep both icons in the DOM and cross-fade over `300ms` with `cubic-bezier(0.2, 0, 0, 1)`.
77
+
78
+ A tab's icon swap and the actions a row reveals on hover fall under **High-frequency interactions get no animation**. Both recipes are in [icon-transitions.md](icon-transitions.md).
79
+
80
+ ## Suppress transitions on theme switch
81
+
82
+ Disable every transition for the theme swap, force a style flush and restore transitions after the next frame. Otherwise every color transition fires at once and the switch smears. See the [recipe](animations.md#suppress-transitions-on-theme-switch).
83
+
84
+ ## Transition only what changes
85
+
86
+ Name the exact properties, as in `transition-property: scale, opacity`, and never `all`. See [performance.md](performance.md).
87
+
88
+ ## Name the animated property in will-change
89
+
90
+ Add `will-change` only after you see first-frame stutter, and name the property you animate: `scale` for `scale`, `transform` for `transform`. Limit it to transform properties, `opacity` and `filter`, and never use `all`. See [performance.md](performance.md#use-will-change-sparingly).
91
+
92
+ ## Hover effects only on hover-capable pointers
93
+
94
+ Put hover-only styling behind `@media (hover: hover)`. On touch, `:hover` latches after a tap and reads as a stuck selected state. Tailwind 4's `hover:` variant already compiles under that query, and Tailwind 3's does not. Where a control draws its own pressed state, set `-webkit-tap-highlight-color: transparent` so the default gray flash does not double it.
95
+
96
+ ## Contain scroll inside overlays
97
+
98
+ Give scrollable dialogs, drawers, menus and side panels `overscroll-behavior: contain`, so scrolling past their end never scrolls the page behind.
99
+
100
+ ## Match icon stroke to text weight
101
+
102
+ An icon's rendered stroke tracks the weight of the text beside it, from `1.5px` at 400 to `2.5px` at 700. Use one icon library per surface. The table, sizing and grid rules are in [icons.md](icons.md).
103
+
104
+ ## One SVG, recolored per state
105
+
106
+ Icons use `currentColor` and take hover, selected and disabled states from CSS color and opacity, never from separate assets. Outline is the default variant, and fill marks the active state. Under `dir="rtl"`, mirror only icons whose meaning follows reading direction. See [icons.md](icons.md#icons-in-rtl).
107
+
108
+ ## Before you finish
109
+
110
+ | Detection | Fix |
111
+ | --- | --- |
112
+ | Padded parent and child with the same `rounded-*` or `border-radius` | Add the padding to the outer radius |
113
+ | `box-shadow: 0 0 0 1px` ring with no `border` beside it | `border: 1px solid transparent` |
114
+ | `outline-slate-*`, `outline-zinc-*` or a hex outline color on `img` | `outline-black/10` and `dark:outline-white/10` |
115
+ | `transition-all` or `transition: all` | Name the changing properties |
116
+ | `animation:` set on `:hover`, `.open` or another toggled class | A transition on the same properties |
117
+ | `active:scale-95`, `scale-90` or `whileTap` below `0.96` | `0.96` |
118
+ | `:active` scale with no `:disabled` exclusion | `enabled:active:` or `:not(:disabled):active` |
119
+ | `bounce:` set to anything but `0` | `bounce: 0` |
120
+ | `opacity: 0` in a base rule that only an `animation` reveals | Hidden state in the `from` keyframe, `animation-fill-mode: both` |
121
+ | `translate`, `scale`, `filter` or `motion.*` animation with no `prefers-reduced-motion`, `motion-safe:` or `MotionConfig` guard | Gate it and cross-fade opacity under reduced motion |
122
+ | Color transitions plus a theme toggle with no `disableTransitionOnChange` or override | The theme-switch suppression recipe |
123
+ | `will-change: all`, or `will-change` on an element that never animates | Name the animated property or delete it |
124
+ | `fill="#..."` or `stroke="#..."` inside an icon SVG | `currentColor` |
125
+ | Plain-CSS `:hover` or Tailwind 3 `hover:` outside `@media (hover: hover)` | Wrap it in the query |
126
+ | `overflow: auto` or `overflow-y-auto` on a dialog, drawer or menu with no `overscroll-behavior` | `overscroll-behavior: contain` |
127
+
128
+ ## Reporting
129
+
130
+ **Severity.** `HIGH` breaks an interaction, as a keyframe toggle that cannot reverse or a hover state stuck on touch does. Two of `interface`'s escalation triggers land here and are `HIGH` on sight. One is motion that ignores `prefers-reduced-motion`, and the other is a state change carried by motion alone. `MEDIUM` is a visible inconsistency in surfaces, icons or motion. `LOW` is isolated polish.
131
+
132
+ **Verification.** Without a browser, read every state the component defines from the code, such as hover, pressed, selected, loading and empty, with its durations and easings. With one, walk each state and replay motion at 10% speed in the browser's Animations panel. Report every check you could not run as `Not verified`.
133
+
134
+ **Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
135
+
136
+ | Severity | Location | Before | After | Why |
137
+ | --- | --- | --- | --- | --- |
138
+
139
+ `Location` is `path/to/file:line`. `Why` names the principle and the user impact.
140
+
141
+ End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable UI-polish findings" and report verification.
@@ -0,0 +1,170 @@
1
+ # Animations
2
+
3
+ Recipes for interruptible transitions, press feedback, first-render behavior, theme switches and the reduced-motion fallback. Staged entrances and exits live in [enter-exit.md](enter-exit.md), and icon swaps in [icon-transitions.md](icon-transitions.md).
4
+
5
+ ## Interruptible animations
6
+
7
+ | | CSS transitions | CSS keyframe animations |
8
+ | --- | --- | --- |
9
+ | **Behavior** | Interpolate toward the latest state | Run on a fixed timeline |
10
+ | **Interrupted** | Retarget mid-flight and reverse | Snap or restart from the beginning |
11
+ | **Use for** | Hover, toggle, open and close | Sequences that run once, such as enters and loading |
12
+
13
+ ```css
14
+ /* Good: clicking again mid-animation reverses smoothly */
15
+ .drawer {
16
+ transform: translateX(-100%);
17
+ transition: transform 200ms ease-out;
18
+ }
19
+ .drawer.open {
20
+ transform: translateX(0);
21
+ }
22
+
23
+ /* Bad: closing mid-animation snaps */
24
+ .drawer.open {
25
+ animation: slideIn 200ms ease-out forwards;
26
+ }
27
+ ```
28
+
29
+ ## Scale on press
30
+
31
+ ```css
32
+ .button {
33
+ transition-property: scale;
34
+ transition-duration: 150ms;
35
+ transition-timing-function: ease-out;
36
+ }
37
+
38
+ .button:not(:disabled):active {
39
+ scale: 0.96;
40
+ }
41
+ ```
42
+
43
+ ```tsx
44
+ // Tailwind
45
+ <button className="transition-transform duration-150 ease-out enabled:active:scale-[0.96]">
46
+ Click me
47
+ </button>
48
+
49
+ // Motion
50
+ <motion.button whileTap={disabled ? undefined : { scale: 0.96 }} disabled={disabled}>
51
+ Click me
52
+ </motion.button>
53
+ ```
54
+
55
+ ### Static prop pattern
56
+
57
+ Where the button has no variant API to carry the opt-out, apply the scale class conditionally on a `static` prop:
58
+
59
+ ```tsx
60
+ const tapScale = "enabled:active:scale-[0.96]";
61
+
62
+ function Button({ static: isStatic, className, children, ...props }) {
63
+ return (
64
+ <button
65
+ className={cn(
66
+ "transition-transform duration-150 ease-out",
67
+ !isStatic && tapScale,
68
+ className,
69
+ )}
70
+ {...props}
71
+ >
72
+ {children}
73
+ </button>
74
+ );
75
+ }
76
+
77
+ // Usage
78
+ <Button>Click me</Button> {/* scales on press */}
79
+ <Button static>Submit</Button> {/* no scale */}
80
+ ```
81
+
82
+ ## Skip animation on page load
83
+
84
+ The icon recipe in [icon-transitions.md](icon-transitions.md#motion) shows `initial={false}` used correctly. It suits icon swaps, toggles, tabs and segmented controls, anything with a default state on page load.
85
+
86
+ Setting it around a first-time entrance skips that entrance entirely. Check the component on a full page refresh before adding it.
87
+
88
+ ```tsx
89
+ // Bad: initial={false} skips the staggered page enter
90
+ <AnimatePresence initial={false}>
91
+ <motion.div initial="hidden" animate="visible" variants={...}>
92
+ ...
93
+ </motion.div>
94
+ </AnimatePresence>
95
+ ```
96
+
97
+ ## Suppress transitions on theme switch
98
+
99
+ Inject a stylesheet that turns off every transition, force a style flush so the new colors commit while it applies, then remove it after the next frame:
100
+
101
+ ```tsx
102
+ "use client";
103
+
104
+ import { useEffect } from "react";
105
+
106
+ export function DisableThemeTransitions() {
107
+ useEffect(() => {
108
+ const mql = window.matchMedia("(prefers-color-scheme: dark)");
109
+
110
+ const handleChange = () => {
111
+ const style = document.createElement("style");
112
+ style.append(
113
+ document.createTextNode(
114
+ "*,*::before,*::after{transition:none !important}"
115
+ )
116
+ );
117
+ document.head.append(style);
118
+
119
+ void document.body.offsetHeight; // forces a synchronous style flush
120
+
121
+ requestAnimationFrame(() => {
122
+ requestAnimationFrame(() => style.remove());
123
+ });
124
+ };
125
+
126
+ mql.addEventListener("change", handleChange);
127
+ return () => mql.removeEventListener("change", handleChange);
128
+ }, []);
129
+
130
+ return null;
131
+ }
132
+ ```
133
+
134
+ The new theme resolves while the override is still in the document, so no transition starts. The nested `requestAnimationFrame` removes the override only after that paint.
135
+
136
+ That covers the OS-level change. An in-app toggle needs the same steps around its own flip: apply the override, change the theme, flush and remove. `next-themes` ships this as `disableTransitionOnChange`.
137
+
138
+ ## High-frequency motion
139
+
140
+ ```css
141
+ /* Good: high-frequency hover gets a minimal transition */
142
+ .row:hover {
143
+ background-color: var(--surface-hover);
144
+ transition: background-color 100ms ease-out;
145
+ }
146
+
147
+ /* Bad: every hover replays a full entrance */
148
+ .row:hover .row-icon {
149
+ animation: bounceIn 500ms;
150
+ }
151
+ ```
152
+
153
+ ## Reduced-motion fallback
154
+
155
+ The opacity fade runs for everyone, and movement, scale and blur join it only without the preference:
156
+
157
+ ```css
158
+ .panel {
159
+ transition: opacity 150ms ease-out;
160
+ }
161
+
162
+ @media (prefers-reduced-motion: no-preference) {
163
+ .panel {
164
+ transition-property: opacity, translate, scale, filter;
165
+ transition-duration: 300ms;
166
+ }
167
+ }
168
+ ```
169
+
170
+ In Tailwind, prefix movement, scale and blur utilities with `motion-safe:`. In Motion, wrap the app in `<MotionConfig reducedMotion="user">`. It turns off transform and layout animations under the preference and keeps opacity. Blur still runs there, so branch on `useReducedMotion()` where a recipe animates `filter`.