@ibis-design/css 0.7.0 → 0.7.1

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 (2) hide show
  1. package/README.md +71 -79
  2. package/package.json +31 -31
package/README.md CHANGED
@@ -8,18 +8,10 @@ Design tokens as CSS custom properties, shared component styles, and a Tailwind
8
8
  npm install @ibis-design/css
9
9
  ```
10
10
 
11
- ## Theming (`data-theme`)
12
-
13
- Import the bundled stylesheet once. All themes share the **same variable names**; values change by `data-theme` on `<html>` (or any ancestor).
14
-
15
- | `data-theme` value | Brand | Mode |
16
- |--------------------|-------|------|
17
- | `ib-light` | Ibis | Light (default) |
18
- | `ib-dark` | Ibis | Dark (placeholder values) |
19
- | `alc-light` | Alchemy | Light |
20
- | `alc-dark` | Alchemy | Dark (placeholder values) |
11
+ ## Quick start
21
12
 
22
- `:root` holds **global** tokens (spacing, shadows, motion, border widths, z-index). `:root` and `[data-theme="ib-light"]` share Ibis light **theme** tokens (colors, typography, radii) for no-JS fallback.
13
+ 1. Import the token stylesheet once in your app entry (or root layout).
14
+ 2. Set `data-theme` on `<html>` (or an ancestor) to pick brand and light/dark mode.
23
15
 
24
16
  ```css
25
17
  @import "@ibis-design/css";
@@ -30,20 +22,49 @@ Import the bundled stylesheet once. All themes share the **same variable names**
30
22
  ```
31
23
 
32
24
  ```js
33
- document.documentElement.dataset.theme = 'alc-dark';
25
+ document.documentElement.dataset.theme = "alc-dark";
34
26
  ```
35
27
 
36
- ### CSS variable naming
28
+ Without the stylesheet and `data-theme`, `var(--color-*)` and other tokens will not resolve.
29
+
30
+ ## Theming (`data-theme`)
31
+
32
+ All themes expose the **same CSS variable names**; only the values change.
33
+
34
+ | `data-theme` | Brand | Mode |
35
+ |--------------|-------|------|
36
+ | `ib-light` | Ibis | Light (default) |
37
+ | `ib-dark` | Ibis | Dark |
38
+ | `alc-light` | Alchemy | Light |
39
+ | `alc-dark` | Alchemy | Dark |
37
40
 
38
- | Category | Pattern | Example |
39
- |----------|---------|---------|
40
- | Color primitive | `color.{palette}.{step}` | `--color-primary-500` |
41
- | Color semantic | `color.{role}` or `color.brand.{name}` | `--color-text-primary`, `--color-brand-secondary` |
42
- | Spacing | `spacing.{n}` | `--spacing-4` |
43
- | Typography size | `font-size.body.{size}` | `--font-size-body-sm` |
44
- | Border radius | `border-radius.{size}` | `--border-radius-md` |
45
- | Shadow | `shadow.elevation.{size}`, `shadow.focus.{variant}` | `--shadow-focus-default` |
46
- | Gradient | `gradient.{name}` | `--gradient-button` |
41
+ **Cascade:**
42
+
43
+ - **Global tokens** (spacing, shadows, motion, border widths, z-index) live on `:root` for every theme.
44
+ - **Theme tokens** (colors, font families/sizes, radii, gradients) come from the active `data-theme` block.
45
+ - **Ibis light** also applies to `:root` when no theme attribute is set (no-JS fallback).
46
+
47
+ Switch themes at runtime:
48
+
49
+ ```js
50
+ document.documentElement.dataset.theme = "alc-light";
51
+ ```
52
+
53
+ ## CSS custom properties
54
+
55
+ ### Naming
56
+
57
+ | Category | Example variable |
58
+ |----------|------------------|
59
+ | Color primitive | `--color-primary-500` |
60
+ | Color semantic | `--color-text-primary`, `--color-brand-secondary` |
61
+ | Spacing | `--spacing-4` |
62
+ | Typography size | `--font-size-body-sm` |
63
+ | Border radius | `--border-radius-md` |
64
+ | Shadow | `--shadow-elevation-sm`, `--shadow-focus-default` |
65
+ | Gradient | `--gradient-button` |
66
+
67
+ ### Example
47
68
 
48
69
  ```css
49
70
  .card {
@@ -55,20 +76,28 @@ document.documentElement.dataset.theme = 'alc-dark';
55
76
  }
56
77
  ```
57
78
 
58
- ### Component CSS
79
+ Semantic brand accents (values differ per theme):
80
+
81
+ - `--color-brand-primary`
82
+ - `--color-brand-secondary`
83
+ - `--color-brand-neutral`
59
84
 
60
- Shared presentation for web components lives in `src/styles/components/` (not in token JSON). Import per component:
85
+ ## Component styles
86
+
87
+ Optional stylesheets for shared `.ibis-*` classes. Import only what you need:
61
88
 
62
89
  ```css
63
90
  @import "@ibis-design/css/components/button.css";
64
91
  @import "@ibis-design/css/components/checkbox.css";
65
92
  ```
66
93
 
67
- Available stylesheets: `banner`, `button`, `checkbox`, `chips`, `dropdown`, `dropdownButton`, `pillTab`, `radio`, `switch`, `textarea`, `textInput`, `textlink`, `tipIndicator`, `toaster`, `tooltip`.
94
+ Available entry points: `banner`, `button`, `checkbox`, `chips`, `dropdown`, `dropdownButton`, `pillTab`, `radio`, `switch`, `textarea`, `textInput`, `textlink`, `tipIndicator`, `toaster`, `tooltip`.
95
+
96
+ If you use **@ibis-design/svelte**, components already import the matching stylesheet; you do not need these unless you use the same class names outside Svelte.
68
97
 
69
- `@ibis-design/svelte` components import these directly (e.g. `import '@ibis-design/css/components/button.css'` in `Button.svelte`).
98
+ ## Tailwind CSS
70
99
 
71
- ### Tailwind preset
100
+ Use the preset in `tailwind.config.js` (Tailwind v3):
72
101
 
73
102
  ```js
74
103
  /** @type {import('tailwindcss').Config} */
@@ -78,65 +107,28 @@ module.exports = {
78
107
  };
79
108
  ```
80
109
 
81
- Dark mode utilities respond to `[data-theme$="-dark"]` (configured in the preset). Load `@ibis-design/css` and set `data-theme` so `var(--color-*)` resolves.
82
-
83
- ## Build
84
-
85
- From the repo root:
86
-
87
- ```bash
88
- npm run build:css
89
- ```
90
-
91
- From this package:
92
-
93
- ```bash
94
- npm run build # build + validate contract
95
- npm run validate # check dist/design-tokens.css only
96
- ```
110
+ - Utilities map to the same `var(--*)` names as the CSS bundle.
111
+ - Dark mode utilities use `[data-theme$="-dark"]` (configured in the preset).
112
+ - You must still import `@ibis-design/css` in your app and set `data-theme` on the document.
97
113
 
98
- The build runs **five Style Dictionary instances** (one global + one per theme) — [documented SD pattern](https://styledictionary.com/reference/config/) when token paths collide across themes. Each instance uses `formatPlatform` (in-memory); results are concatenated into one file. No CSS regex merging.
99
-
100
- 1. `global.json` → `:root` block in `dist/design-tokens.css`
101
- 2. Each `themes/{id}.json` → `[data-theme="…"]` block (ib-light also targets `:root` for no-JS fallback)
102
- 3. `dist/tokens/{themeId}.json` — flat `--var` maps via custom `json/css-vars-flat` format
103
- 4. `src/tailwind.preset.js` (hand-written) + generated `dist/tailwind.theme.js`
104
- 5. Copy `src/styles/components/*.css` → `dist/components/`
105
-
106
- Do not edit `dist/` by hand. Change tokens in `src/tokens/` and rebuild.
107
-
108
- ## Token source layout
109
-
110
- | Path | Role |
111
- |------|------|
112
- | `src/tokens/global.json` | Spacing, shadows, motion, border widths, z-index, opacity, sizes |
113
- | `src/tokens/themes/ib-light.json` | Ibis light colors, fonts, radii, gradients |
114
- | `src/tokens/themes/ib-dark.json` | Minimal dark overrides + PLACEHOLDER descriptions |
115
- | `src/tokens/themes/alc-light.json` | Alchemy light |
116
- | `src/tokens/themes/alc-dark.json` | Minimal dark overrides |
117
- | `src/tokens/contract/required-keys.json` | CI contract for required CSS variables |
118
-
119
- Tokens use [DTCG](https://design-tokens.github.io/community-group/format/) JSON.
120
-
121
- ### Brand semantics
122
-
123
- Every theme defines:
124
-
125
- - `color.brand.primary`
126
- - `color.brand.secondary`
127
- - `color.brand.neutral`
114
+ ## Fonts
128
115
 
129
- Alchemy maps legacy `brand.blue` / yellow accents into these keys (see `docs/tokens-and-build.md`).
116
+ Font family tokens (Inter, Metrisch, Beyond Infinity, etc.) are **not** bundled. Load the fonts in your application to match the stacks referenced in the tokens.
130
117
 
131
- ## Fonts
118
+ ## Package entry points
132
119
 
133
- Token font stacks (Inter, Metrisch, Beyond Infinity, etc.) are not bundled. Load fonts in your application to match the token values.
120
+ | Import | Purpose |
121
+ |--------|---------|
122
+ | `@ibis-design/css` | Full design token stylesheet (`design-tokens.css`) |
123
+ | `@ibis-design/css/design-tokens.css` | Same as default export |
124
+ | `@ibis-design/css/tailwind.preset` | Tailwind preset (includes dark mode selector) |
125
+ | `@ibis-design/css/components/<name>.css` | Per-component presentation CSS |
134
126
 
135
- ## Legacy imports
127
+ ### Legacy paths
136
128
 
137
- These paths resolve to the unified bundle:
129
+ These resolve to the same unified token bundle as `@ibis-design/css`:
138
130
 
139
131
  - `@ibis-design/css/ibis-design.css`
140
132
  - `@ibis-design/css/alchemy-design.css`
141
133
 
142
- Prefer `@ibis-design/css` or `@ibis-design/css/design-tokens.css` and control brand/mode with `data-theme`.
134
+ Prefer `@ibis-design/css` and switch brand/mode with `data-theme` instead of separate brand CSS files.
package/package.json CHANGED
@@ -1,31 +1,31 @@
1
- {
2
- "name": "@ibis-design/css",
3
- "version": "0.7.0",
4
- "description": "Design tokens, CSS variables, and Tailwind preset for the IBIS design system.",
5
- "type": "module",
6
- "exports": {
7
- ".": "./dist/design-tokens.css",
8
- "./design-tokens.css": "./dist/design-tokens.css",
9
- "./tailwind.preset": "./dist/tailwind.preset.js",
10
- "./preset": "./dist/tailwind.preset.js",
11
- "./ibis-design.css": "./dist/design-tokens.css",
12
- "./alchemy-design.css": "./dist/design-tokens.css",
13
- "./ibis/tailwind.preset": "./dist/tailwind.preset.js",
14
- "./alchemy/tailwind.preset": "./dist/tailwind.preset.js",
15
- "./components/*": "./dist/components/*",
16
- "./tailwind.theme": "./dist/tailwind.theme.js"
17
- },
18
- "files": [
19
- "dist"
20
- ],
21
- "scripts": {
22
- "build": "tsx src/scripts/build.ts && tsx src/scripts/validate-themes.ts",
23
- "validate": "tsx src/scripts/validate-themes.ts",
24
- "prepublishOnly": "npm run build"
25
- },
26
- "devDependencies": {
27
- "sd-tailwindcss-transformer": "^2.2.1",
28
- "style-dictionary": "^5.4.1",
29
- "tsx": "^4.22.3"
30
- }
31
- }
1
+ {
2
+ "name": "@ibis-design/css",
3
+ "version": "0.7.1",
4
+ "description": "Design tokens, CSS variables, and Tailwind preset for the IBIS design system.",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./dist/design-tokens.css",
8
+ "./design-tokens.css": "./dist/design-tokens.css",
9
+ "./tailwind.preset": "./dist/tailwind.preset.js",
10
+ "./preset": "./dist/tailwind.preset.js",
11
+ "./ibis-design.css": "./dist/design-tokens.css",
12
+ "./alchemy-design.css": "./dist/design-tokens.css",
13
+ "./ibis/tailwind.preset": "./dist/tailwind.preset.js",
14
+ "./alchemy/tailwind.preset": "./dist/tailwind.preset.js",
15
+ "./components/*": "./dist/components/*",
16
+ "./tailwind.theme": "./dist/tailwind.theme.js"
17
+ },
18
+ "files": [
19
+ "dist"
20
+ ],
21
+ "scripts": {
22
+ "build": "tsx src/scripts/build.ts && tsx src/scripts/validate-themes.ts",
23
+ "validate": "tsx src/scripts/validate-themes.ts",
24
+ "prepublishOnly": "npm run build"
25
+ },
26
+ "devDependencies": {
27
+ "sd-tailwindcss-transformer": "^2.2.1",
28
+ "style-dictionary": "^5.4.1",
29
+ "tsx": "^4.22.3"
30
+ }
31
+ }