@terrahq/design-system 0.0.9 → 0.2.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.
package/README.md CHANGED
@@ -1,178 +1,95 @@
1
1
  # @terrahq/design-system
2
2
 
3
- This package is a small helper for building demos or small projects outside of our regular ecosystem.
3
+ [![npm](https://img.shields.io/npm/v/@terrahq/design-system)](https://www.npmjs.com/package/@terrahq/design-system)
4
4
 
5
- You can include the following stylesheet in your project:
5
+ Terra CSS classes for building demos and prototypes outside our regular ecosystem: the same colors, type scale, radius and spacing as Terra's sites, as plain classes you can write straight in your HTML.
6
6
 
7
- ```
8
- <link rel="stylesheet" href="https://unpkg.com/@terrahq/design-system@latest/dist/style.css">
7
+ > **Experimental.** This project is a work in progress: class names, options and docs may still change. Not intended for production projects. For those, use Terra's own setup.
8
+
9
+ ## Install
9
10
 
11
+ **From a CDN (nothing to install):**
12
+
13
+ ```html
14
+ <link rel="stylesheet" href="https://unpkg.com/@terrahq/design-system@latest/dist/style.css">
10
15
  ```
11
16
 
12
- ### Features
17
+ Pin a version instead of `latest` if the page must never change: `@terrahq/design-system@0.1.0`.
18
+
19
+ **From npm:**
13
20
 
14
- ### breakpoints names
21
+ ```bash
22
+ npm i @terrahq/design-system
15
23
  ```
16
- desktop: 1700px;
17
- laptop: 1570px;
18
- tabletl: 1300px;
19
- tabletm: 1024px;
20
- tablets: 810px;
21
- mobile: 580px;
24
+
25
+ ```js
26
+ import '@terrahq/design-system' // resolves to dist/style.css
22
27
  ```
23
28
 
24
- ### colors
29
+ ## Use it
25
30
 
31
+ ```html
32
+ <article class="f--background-b f--radius-c f--shadow-a u--p-4 u--display-flex u--flex-direction-column u--gap-2">
33
+ <span class="f--background-d f--color-a f--font-f u--px-2 f--radius-full">new</span>
34
+ <h3 class="f--font-c u--font-bold">Project Atlas</h3>
35
+ <p class="f--font-e">Built only with classes.</p>
36
+ </article>
26
37
  ```
27
- /* Core Colors */
28
- $color-a: #0f0f0f;
29
- $color-b: #fefefe;
30
- $color-c: #f7f8f4;
31
-
32
- /* Accent Color */
33
- $color-d: #7ce55e;
34
- $color-e: #2d9f66;
35
- $color-f: #429ed6;
36
- $color-g: #fdb335;
37
- $color-h: #f76e4a;
38
- $color-i: #f58dd7;
38
+
39
+ ## Two layers
40
+
41
+ | Layer | What it is | Examples |
42
+ |---|---|---|
43
+ | `f--` **foundation** | Terra's design decisions. Several properties per class, responsive included. They don't change between versions. | `f--font-c`, `f--color-a`, `f--background-d`, `f--radius-c`, `f--shadow-a`, `f--row`, `f--col-6` |
44
+ | `u--` **utilities** | One property per class, with a variant per breakpoint. | `u--p-4`, `u--p-mobile-2`, `u--display-flex`, `u--border-a` |
45
+
46
+ If a foundation class already covers something, there is no utility for it. To tweak one detail of a foundation class, add a utility: `f--font-c u--font-bold`. Utilities load after foundation, so they win.
47
+
48
+ **Breakpoints** (`max-width`): `desktop` 1700 · `laptop` 1570 · `tabletl` 1300 · `tabletm` 1024 · `tablets` 810 · `mobile` 580. Utilities take the name in the middle: `u--p-mobile-2`.
49
+
50
+ **Typography.** `f--font-a` to `f--font-f` use Uncut Sans, then `system-ui`. The package does **not** ship the font files; load Uncut Sans yourself or the browser falls back to `system-ui`.
51
+
52
+ All classes are listed in the [class reference](docs/CLASSES.md).
53
+
54
+ ## Configure your own build
55
+
56
+ The CDN file is the same for everyone. To change the palette, spacing, radius or font, describe it in a `terra.config.js` and generate your own CSS (needs Node 18+):
57
+
58
+ ```bash
59
+ npm i @terrahq/design-system
60
+ cp node_modules/@terrahq/design-system/terra.config.example.js terra.config.js
61
+ npx terra-ds build
62
+ ```
63
+
64
+ ```js
65
+ // terra.config.js
66
+ export default {
67
+ colors: { a: '#0f0f0f', b: '#fefefe', j: '#ff00aa' }, // replaces the palette; "a" and "b" are required
68
+ backgrounds: ['a', 'b', 'j'], // which colors get f--background-*
69
+ spacing: [0, 1, 2, 4, 8], // replaces the u--p-*, u--m-*, u--gap-* steps (x 8px)
70
+ font: "'Uncut Sans', system-ui, sans-serif", // font-family of f--font-*
71
+ radius: { a: '4px', full: '999px' }, // replaces f--radius-*
72
+ output: 'public/terra.css',
73
+ }
39
74
  ```
40
- <br><br>
41
75
 
42
- #### Foundation
43
-
44
- - **Grid System:**
45
- - **Container:** `.f--container`, `.f--container--fluid`, `.f--container--tabletm-fluid`
46
- - Examples: `.f--container` (max-width), `.f--container--fluid` (full-width)
47
-
48
- - **Row:** `.f--row`, `.f--row--remove-gutter`
49
- - Examples: `.f--row` (with gutter), `.f--row--remove-gutter` (no spacing)
50
-
51
- - **Columns:** `.f--col-#{$i}` (1 to 12) or `.f--col-#{$size}-#{$i}`
52
- - Examples: `.f--col-6`, `.f--col-12`, `.f--col-desktop-8`, `.f--col-mobile-4`
53
-
54
- - **Offset:** `.f--offset-#{$i}` (0 to 11) or `.f--offset-#{$size}-#{$i}`
55
- - Examples: `.f--offset-2`, `.f--offset-desktop-3`, `.f--offset-mobile-1`
56
-
57
- - **Color:** Terra Branded colors `.f--color-#{letter}`
58
- - Examples: `.f--color-a`, `.f--color-d`, `.f--color-i`
59
-
60
- - **Background:** Terra Brand Colors `.f--bg-#{letter}`
61
- - Examples: `.f--bg-a`, `.f--bg-b`, `.f--bg-e`
62
-
63
- - **Section:** `.f--section-#{letter}`
64
- - Examples: `.f--section-a`, `.f--section-c`, `.f--section-f`
65
-
66
- - **Gap:** `.f--gap-#{letter}`
67
- - Examples: `.f--gap-a`, `.f--gap-b`, `.f--gap-d`
68
-
69
- #### Utilities
70
-
71
- - **Align Items** `.u--align-items-#{$name}` or `.u--align-items-#{$breakpoint-name}-#{$name}`
72
-
73
- | Value | Class | CSS Property |
74
- |-------|-------|--------------|
75
- | baseline | `.u--align-items-baseline` | `align-items: baseline` |
76
- | flex-start | `.u--align-items-flex-start` | `align-items: flex-start` |
77
- | flex-end | `.u--align-items-flex-end` | `align-items: flex-end` |
78
- | center | `.u--align-items-center` | `align-items: center` |
79
-
80
- **With breakpoints:** `.u--align-items-desktop-center`, `.u--align-items-mobile-flex-start`, etc.
81
-
82
- - **Display** `.u--display-#{$name}` or `.u--display-#{$breakpoint-name}-#{$name}`
83
-
84
- | Value | Class | CSS Property |
85
- |-------|-------|--------------|
86
- | block | `.u--display-block` | `display: block` |
87
- | none | `.u--display-none` | `display: none` |
88
- | inline-block | `.u--display-inline-block` | `display: inline-block` |
89
- | inline | `.u--display-inline` | `display: inline` |
90
- | flex | `.u--display-flex` | `display: flex` |
91
- | inline-flex | `.u--display-inline-flex` | `display: inline-flex` |
92
-
93
- **With breakpoints:** `.u--display-desktop-flex`, `.u--display-mobile-block`, etc.
94
-
95
- - **Flex-wrap** `.u--flex-wrap-#{$name}` or `.u--flex-wrap-#{$breakpoint-name}-#{$name}`
96
- - Examples: `.u--flex-wrap-wrap`, `.u--flex-wrap-nowrap`, `.u--flex-wrap-tablets-wrap`
97
-
98
- - **Font Style** `.u--font-style-#{$name}` or `.u--font-style-#{$breakpoint-name}-#{$name}`
99
- - Examples: `.u--font-style-italic`, `.u--font-style-normal`, `.u--font-style-mobile-italic`
100
-
101
- - **Font Weight** `.u--font-#{$name}` or `.u--font-#{$breakpoint-name}-#{$name}`
102
-
103
- | Value | Class | CSS Property |
104
- |-------|-------|--------------|
105
- | thin | `.u--font-thin` | `font-weight: 100` |
106
- | extralight | `.u--font-extralight` | `font-weight: 200` |
107
- | light | `.u--font-light` | `font-weight: 300` |
108
- | regular | `.u--font-regular` | `font-weight: 400` |
109
- | medium | `.u--font-medium` | `font-weight: 500` |
110
- | semibold | `.u--font-semibold` | `font-weight: 600` |
111
- | bold | `.u--font-bold` | `font-weight: 700` |
112
- | extrabold | `.u--font-extrabold` | `font-weight: 800` |
113
- | black | `.u--font-black` | `font-weight: 900` |
114
-
115
- **With breakpoints:** `.u--font-desktop-bold`, `.u--font-mobile-light`, etc.
116
-
117
- - **Justify Content** `.u--justify-content-#{$name}` or `.u--justify-content-#{$breakpoint-name}-#{$name}`
118
-
119
- | Value | Class | CSS Property |
120
- |-------|-------|--------------|
121
- | space-between | `.u--justify-content-space-between` | `justify-content: space-between` |
122
- | space-around | `.u--justify-content-space-around` | `justify-content: space-around` |
123
- | space-evenly | `.u--justify-content-space-evenly` | `justify-content: space-evenly` |
124
- | flex-start | `.u--justify-content-flex-start` | `justify-content: flex-start` |
125
- | flex-end | `.u--justify-content-flex-end` | `justify-content: flex-end` |
126
- | center | `.u--justify-content-center` | `justify-content: center` |
127
-
128
- **With breakpoints:** `.u--justify-content-desktop-center`, `.u--justify-content-mobile-flex-start`, etc.
129
-
130
- - **Overflow** `.u--overflow-#{$name}` or `.u--overflow-#{$breakpoint-name}-#{$name}`
131
- - Examples: `.u--overflow-hidden`, `.u--overflow-auto`, `.u--overflow-tablets-scroll`
132
-
133
- - **Position** `.u--position-#{$name}` or `.u--position-#{$breakpoint-name}-#{$name}`
134
- - Examples: `.u--position-relative`, `.u--position-absolute`, `.u--position-desktop-fixed`
135
-
136
- - **Aspect Ratio** `.u--ar-#{$name}` or `.u--ar-#{$breakpoint-name}-#{$name}`
137
-
138
- | Value | Class | CSS Property | Ratio |
139
- |-------|-------|--------------|-------|
140
- | a | `.u--ar-a` | `aspect-ratio: 1.77777777` | 16:9 |
141
- | b | `.u--ar-b` | `aspect-ratio: 1.33333333` | 4:3 |
142
- | c | `.u--ar-c` | `aspect-ratio: 1.5` | 3:2 |
143
- | d | `.u--ar-d` | `aspect-ratio: 1` | 1:1 |
144
- | e | `.u--ar-e` | `aspect-ratio: 0.75` | 3:4 |
145
- | f | `.u--ar-f` | `aspect-ratio: 0.33333333` | 1:3 |
146
-
147
- **With breakpoints:** `.u--ar-desktop-a`, `.u--ar-mobile-d`, etc.
148
-
149
- - **Spacing** `.u--#{$attr-short}-#{$value}` or `.u--#{$attr-short}-#{$breakpoint-name}-#{$value}`
150
-
151
- | Property | Prefix | Values | Example Classes |
152
- |----------|--------|--------|-----------------|
153
- | padding | `p` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--p-2`, `.u--p-5` |
154
- | padding-top | `pt` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--pt-1`, `.u--pt-4` |
155
- | padding-right | `pr` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--pr-2`, `.u--pr-8` |
156
- | padding-bottom | `pb` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--pb-3`, `.u--pb-10` |
157
- | padding-left | `pl` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--pl-1`, `.u--pl-15` |
158
- | margin | `m` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--m-2`, `.u--m-7` |
159
- | margin-top | `mt` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--mt-1`, `.u--mt-5` |
160
- | margin-right | `mr` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--mr-3`, `.u--mr-8` |
161
- | margin-bottom | `mb` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--mb-2`, `.u--mb-10` |
162
- | margin-left | `ml` | 0, 1, 2, 3, 4, 5, 7, 8, 10, 15 | `.u--ml-4`, `.u--ml-15` |
163
-
164
- **With breakpoints:** `.u--mb-desktop-2`, `.u--p-mobile-4`, `.u--mt-tablets-1`, etc.
76
+ Every key is optional. "Replaces" means what you don't list is not generated, which also makes the file smaller (about 77 kB with five spacing steps, against 108 kB by default). Breakpoints, grid and shadows are not configurable yet.
77
+
78
+ ## What's new in 0.2.0
79
+
80
+ - **States:** `u--hover-background-*`, `u--hover-color-*`, `u--hover-border-*`, `u--focus-ring`, `u--active-scale-90|95|98`, `u--disabled-opacity-25|50|75`, and `u--group` with `u--group-hover-*` for children of a hovered parent. Hover only applies on devices that can hover. States have no breakpoint variants.
81
+ - **Motion:** `u--transition-all|colors|opacity|transform`, `u--duration-a|b|c` (0.1s, 0.3s, 0.6s), `u--ease-standard|entrance|exit-a|b`, and the animations `u--animation-fade-in`, `fade-up`, `spin` and `pulse`, which respect `prefers-reduced-motion`.
82
+ - Everything is additive: every 0.1.0 rule is unchanged.
83
+
84
+ ## What's new in 0.1.0
85
+
86
+ - **`terra-ds build`** and `terra.config.js` to configure palette, spacing, radius and font.
87
+ - **New foundation classes:** `f--radius-*`, `f--shadow-*`.
88
+ - **New utilities:** `u--border-*`, `u--px/py/mx/my`, `u--gap`, `u--row-gap`, `u--col-gap`, `u--mx-auto`, and spacing steps 6, 9 and 12.
89
+ - **Changed default:** `f--font-*` now uses Uncut Sans (with `system-ui` as fallback) instead of Arial. Every other existing class is unchanged.
90
+
91
+ ## More
165
92
 
166
- - **Text-align** `.u--text-align-#{$name}` or `.u--text-align-#{$breakpoint-name}-#{$name}`
167
-
168
- | Value | Class | CSS Property |
169
- |-------|-------|--------------|
170
- | left | `.u--text-align-left` | `text-align: left` |
171
- | center | `.u--text-align-center` | `text-align: center` |
172
- | right | `.u--text-align-right` | `text-align: right` |
173
- | justify | `.u--text-align-justify` | `text-align: justify` |
174
-
175
- **With breakpoints:** `.u--text-align-desktop-center`, `.u--text-align-mobile-left`, etc.
176
-
177
- <br>
178
- Note: This is not intended for use in ongoing projects.
93
+ - [Class reference](docs/CLASSES.md)
94
+ - [How Terra works](TERRA.md): colors, type, shape, motion and voice
95
+ - [Contributing](CONTRIBUTING.md)
@@ -0,0 +1,46 @@
1
+ #!/usr/bin/env node
2
+ // Usage: npx terra-ds build [terra.config.js] -> writes the CSS to config.output
3
+ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
4
+ import { dirname, resolve } from 'node:path'
5
+ import { fileURLToPath, pathToFileURL } from 'node:url'
6
+ import * as sass from 'sass'
7
+
8
+ const scssRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../src/scss')
9
+ const [cmd, file = 'terra.config.js'] = process.argv.slice(2)
10
+ if (cmd !== 'build') { console.error('Usage: terra-ds build [terra.config.js]'); process.exit(1) }
11
+
12
+ const path = resolve(process.cwd(), file)
13
+ if (!existsSync(path)) { console.error(`Config not found: ${path}`); process.exit(1) }
14
+ const cfg = (await import(pathToFileURL(path))).default
15
+
16
+ // config key -> Sass variable. Anything set here replaces the default (palette, spacing).
17
+ const map = o => `(${Object.entries(o).map(([k, v]) => `${k}: ${v}`).join(', ')})`
18
+ const list = a => `(${a.join(', ')})`
19
+ const vars = []
20
+ if (cfg.colors) {
21
+ if (!cfg.colors.a || !cfg.colors.b) { console.error('colors must include "a" and "b" (the reset uses them)'); process.exit(1) }
22
+ vars.push(`$color-options: ${map(cfg.colors)}`)
23
+ }
24
+ if (cfg.backgrounds) vars.push(`$colorbg-keys: ${list(cfg.backgrounds)}`)
25
+ if (cfg.font) vars.push(`$type-a: (${cfg.font})`)
26
+ if (cfg.radius) vars.push(`$radius-options: ${map(cfg.radius)}`)
27
+ if (cfg.spacing) {
28
+ const bad = cfg.spacing.filter(n => !Number.isInteger(n) || n < 0)
29
+ if (bad.length) { console.error(`spacing steps must be whole numbers, 0 or higher (got ${bad.join(', ')}). Each step is that number x 8px.`); process.exit(1) }
30
+ }
31
+ if (cfg.spacing) vars.push(`$space-values: ${list(cfg.spacing)}`)
32
+
33
+ const { css } = sass.compileString(
34
+ `@use "@scss/index"${vars.length ? ` with (${vars.join(', ')})` : ''};`,
35
+ {
36
+ style: 'compressed',
37
+ // Newer Sass flags the if() calls in the existing utilities; the output is correct, so keep the CLI quiet.
38
+ silenceDeprecations: ['if-function'],
39
+ importers: [{ findFileUrl: u => u.startsWith('@scss/') ? pathToFileURL(resolve(scssRoot, u.slice(6))) : null }],
40
+ },
41
+ )
42
+
43
+ const out = resolve(process.cwd(), cfg.output ?? 'terra.css')
44
+ mkdirSync(dirname(out), { recursive: true })
45
+ writeFileSync(out, css)
46
+ console.log(`terra-ds: ${out} (${(css.length / 1024).toFixed(1)} kB)`)