@kjaniec-dev/design 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.
- package/README.md +70 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# @kjaniec-dev/design
|
|
2
|
+
|
|
3
|
+
Design tokens, theme configuration, and Tailwind CSS `@theme` bridge for the **KJ Product Kit**.
|
|
4
|
+
|
|
5
|
+
This package serves as the **source of truth** for all visual properties (colors, typography, spacing, border radii, shadows) used across the component library and any consumer applications.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. How it Works
|
|
10
|
+
|
|
11
|
+
The design tokens are defined in a structured JSON schema and compiled into CSS assets for consumption:
|
|
12
|
+
|
|
13
|
+
* **`tokens.json` (Source of Truth):** Contains token values for layout variables, light theme colors, dark theme colors, border radii, and box shadows.
|
|
14
|
+
* **`build-tokens.js` (Compiler):** A build script that parses the tokens JSON and generates:
|
|
15
|
+
* `src/theme.css`: Declares raw CSS custom properties (`--kj-*`). It maps variables under the `:root` pseudo-class and overrides them for the `.dark` selector (automatic dark mode).
|
|
16
|
+
* `src/tailwind.css`: Contains Tailwind CSS `@theme` mapping directives, hooking the token values directly into the Tailwind v4 compilation pipeline.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 2. Compile Tokens
|
|
21
|
+
|
|
22
|
+
To rebuild the theme stylesheets after modifying `tokens.json`, run:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm run build
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
*Note: The compile step runs automatically inside the `prepublishOnly` hook before publishing the package to npm.*
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 3. Usage in Applications
|
|
33
|
+
|
|
34
|
+
### Installation
|
|
35
|
+
Install the design tokens package alongside the companion React components library:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install @kjaniec-dev/design @kjaniec-dev/ui
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Stylesheet Setup
|
|
42
|
+
Import the Tailwind theme bridge at the top of your global CSS stylesheet (Vite, Next.js, etc.):
|
|
43
|
+
|
|
44
|
+
```css
|
|
45
|
+
@import "tailwindcss";
|
|
46
|
+
@import "@kjaniec-dev/design/tailwind.css";
|
|
47
|
+
@import "@kjaniec-dev/ui/ui.css";
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Once imported, you can use any of the design kit theme mappings natively in your HTML or component class lists (e.g., `bg-primary`, `text-primary-foreground`, `rounded-kj-md`, `shadow-kj-sm`).
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 4. Theme Configuration
|
|
55
|
+
|
|
56
|
+
Colors and typography variables are declared semantically:
|
|
57
|
+
* **Primary/Secondary/Success/Warning/Danger/Info:** Brand colors with automated hover and surface variants.
|
|
58
|
+
* **Canvas & Surface:** Background tokens used for page layouts and card/panel elements.
|
|
59
|
+
* **Border & Ring:** Layout boundary and focus indicator styles.
|
|
60
|
+
|
|
61
|
+
### Dark Mode
|
|
62
|
+
Dark mode is activated simply by adding the `.dark` class to an ancestor container (e.g. `<html>` or `<body>`):
|
|
63
|
+
|
|
64
|
+
```html
|
|
65
|
+
<html class="dark">
|
|
66
|
+
<body class="bg-canvas text-foreground">
|
|
67
|
+
<!-- Everything here automatically switches to dark-theme tokens -->
|
|
68
|
+
</body>
|
|
69
|
+
</html>
|
|
70
|
+
```
|