@jsenv/navi 0.29.46 → 0.29.47
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.
- package/dist/jsenv_navi.js +96 -72
- package/dist/jsenv_navi.js.map +3 -3
- package/docs/css_architecture.md +52 -0
- package/package.json +1 -1
package/docs/css_architecture.md
CHANGED
|
@@ -65,6 +65,57 @@ Props are the primary way to customize appearance. They translate to inline `sty
|
|
|
65
65
|
<Button style={{ "--button-height": "48px" }} />
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
+
#### Variants set defaults, never resolved values
|
|
69
|
+
|
|
70
|
+
A control resolves each styled property in two steps: the public variable
|
|
71
|
+
holds what was asked for (`--picker-background-color`), and an internal
|
|
72
|
+
`--x-` variable holds what is finally painted, per state:
|
|
73
|
+
|
|
74
|
+
```css
|
|
75
|
+
.navi_picker {
|
|
76
|
+
--x-picker-background-color: var(--picker-background-color);
|
|
77
|
+
|
|
78
|
+
&[data-hover] {
|
|
79
|
+
--x-picker-background-color: var(--picker-background-color-hover);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
A variant (`icon`, `discrete`, `bare`, `border`, `headless`…) describes what
|
|
85
|
+
the caller did **not** say, so it writes the public variable — the default —
|
|
86
|
+
and never the `--x-` one:
|
|
87
|
+
|
|
88
|
+
```css
|
|
89
|
+
&[data-variant="icon"] {
|
|
90
|
+
/* ✅ a default: a backgroundColor prop, being inline on this same element, wins */
|
|
91
|
+
--picker-background-color: transparent;
|
|
92
|
+
/* ❌ a verdict: the prop is read, translated, and then thrown away */
|
|
93
|
+
--x-picker-background-color: transparent;
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Writing `--x-` from a variant is the one failure mode that costs real time to
|
|
98
|
+
diagnose: the prop is accepted, it reaches its variable with the right value,
|
|
99
|
+
and nothing happens. A prop silently without effect is worse than a prop
|
|
100
|
+
refused.
|
|
101
|
+
|
|
102
|
+
Two things come with moving the default:
|
|
103
|
+
|
|
104
|
+
- the **per-state** variables are derived from the base one by formula
|
|
105
|
+
(`hover` = 5% black over the background, `disabled` = 5% grey), so a variant
|
|
106
|
+
that clears the background must re-point them at the base
|
|
107
|
+
(`--picker-background-color-hover: var(--picker-background-color)`), or a box
|
|
108
|
+
reappears on hover under a control that is supposed to have none. When the
|
|
109
|
+
variant does have a resting movement, express it as a mix **into** the
|
|
110
|
+
background (`color-mix(in srgb, currentColor 8%, var(--picker-background-color))`)
|
|
111
|
+
rather than a replacement, so it still composes with a color the caller gave.
|
|
112
|
+
- a variable fed by another prop keeps that chain in its fallback:
|
|
113
|
+
`--button-background-color: var(--button-background, transparent)` leaves both
|
|
114
|
+
`background` and `backgroundColor` working.
|
|
115
|
+
|
|
116
|
+
The same holds for sizing: a variant lowers `--picker-padding-x-default`, not
|
|
117
|
+
`--x-picker-padding-left`.
|
|
118
|
+
|
|
68
119
|
### 2. CSS variables (for global or theme-level changes)
|
|
69
120
|
|
|
70
121
|
When the same change applies to many components (e.g. a design token update), set the variable at a higher scope:
|
|
@@ -200,3 +251,4 @@ Overriding the actual CSS rules (not the variables) is intentionally hard — th
|
|
|
200
251
|
| A global design token | `--navi-*` on `:root` |
|
|
201
252
|
| How wide popups may ever get | `--navi-app-max-width` on `:root` |
|
|
202
253
|
| A structural layout rule | Expose a new CSS variable (contribute) |
|
|
254
|
+
| What a variant decided | A prop — a variant only ever moves defaults, so props keep winning |
|