@quieto/design-tokens 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# @quieto/design-tokens
+
+## 0.2.0
+
+### Minor Changes
+
+- 35c897a: Add `qds-accordion` and `qds-accordion-item`: collapsible sections following the ARIA accordion pattern, with a configurable heading level, an exclusive mode, arrow-key movement between headings, and closed panels that find-in-page can still search. Styled by the new `component/accordion` token set.
+- 99ce48f: Add `qds-card`: a container with media, header, body, and footer regions in outlined, elevated, and filled variants. Empty regions are hidden in CSS, so server-rendered cards lay out correctly before hydration. Styled by the new `component/card` token set.
+- db92c5e: Add `qds-checkbox`: a form-associated checkbox with checked, indeterminate, disabled, and required states, styled by the new `component/checkbox` token set.
+- b7d1206: Add `qds-chip`: a compact status or category label in five variants, with an optional remove button that fires `qds-remove`. Styled by the new `component/chip` token set.
+- ad84c23: Add `qds-input`: a form-associated single-line text input with sizes, start and end slots, and native constraint validation, styled by the new `component/input` token set.
+- a8ac72b: Add `qds-modal`: a modal dialog built on the native `<dialog>` and `showModal()`, with three sizes, opt-in light dismiss, and support for slotted `<form method="dialog">`. Styled by the new `component/modal` token set.
+- 6cb64b1: Add `qds-progress-bar`: determinate and indeterminate progress in four variants, announced with the progressbar role and pulsing instead of sliding under reduced motion. Styled by the new `component/progress-bar` token set.
+- ae223c6: Add `qds-radio-group` and `qds-radio`: a form-associated radio group with roving-tabindex arrow-key navigation, required validation, and block or inline layout, styled by the new `component/radio` token set.
+- afc271a: Add `qds-tabs`, `qds-tab`, and `qds-tab-panel`: tabs following the ARIA tabs pattern with automatic activation, roving tabindex, RTL-aware arrow keys, and disabled tabs. Styled by the new `component/tabs` token set.
+- 06555a5: Add `qds-text-field`: a complete form-associated text field with a visible label, hint, and error message wired to the input, showing native validation messages once the user leaves the field. Styled by the new `component/text-field` token set.
+- cc1def3: Add `qds-toggle`: a form-associated on/off switch, announced with the switch role, styled by the new `component/toggle` token set.
+- 7e3368b: Add a selectable mode to `qds-chip` for filter chips: the chip becomes a toggle button with `aria-pressed`, shows a check mark while `selected`, fires `qds-change`, and supports `disabled`. Styled by new `chip.selectable` and `chip.selected` tokens.
+- 5027635: Add `color.black.5` through `color.black.60`, black at those opacity percentages, and use them for `elevation.subtle` and `elevation.default` in both modes. Shadows are now translucent rather than solid gray, so they soften in light mode and stay visible in dark mode.
+- f99af90: Add `size` and `opacity` primitive categories: `size.sm` through `size.xl` for container widths, which outgrow the spacing scale, and `opacity.0` through `opacity.100`. The modal's widths and backdrop opacity now reference them instead of holding raw values.
+- 6c5499c: Add `color.content.inverse` for content on a filled surface: button labels on primary and danger buttons, checkbox check marks, radio dots, and toggle thumbs. It is light in light mode and dark in dark mode. Previously these used `neutral.50` in both modes, which fell to 3.5:1 on the lighter filled colors of dark mode; they now reach at least 4.6:1 in both modes.
+- 822aa9e: Add three semantic roles and status border colors.
+
+  - `error` is a status role alongside `info`, `success`, and `warning`: `color.background.error` (a tint), `color.content.error`, and `color.border.error`. `danger` stays the action role for destructive buttons.
+  - `color.border.control` is the boundary of an interactive control and reaches 3:1 against the page. Inputs, text fields, unchecked checkboxes and radios, and the off toggle track use it.
+  - `color.background.raised` is the surface of something elevated. It lightens in dark mode, where a shadow cannot be seen; elevated cards and the modal use it.
+  - `color.border.info`, `success`, `warning`, and `error` reach 3:1 against the page, and also color progress bar fills — so the warning bar is amber rather than brown.
+
+  **Breaking:** the `danger` variant of `qds-chip` and `qds-progress-bar` is renamed `error`, since both show a status rather than a destructive action. The error chip is now tinted like the other statuses instead of outlined.
+
+## 0.1.0
+
+### Minor Changes
+
+- First publishable release.
+
+  - Ships no runtime dependencies. Style Dictionary and the Tokens Studio transforms were declared as dependencies, so installing the package pulled in 114 packages; they are build tools and now install only for development.
+  - `require()` works on Node versions that support requiring ES modules, via a `default` export condition.
+  - TypeScript types resolve with `moduleResolution: "node"` as well as `bundler` and `node16`.
+  - `@quieto/design-tokens/nomenclature` now has type declarations.
+  - Removed the `engines` constraint; the published files do not need Node 22.
+  - Added a README covering setup, light and dark mode, and which tier to use.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dillon Schultz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @quieto/design-tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Design tokens for the Quieto Design System, shipped as CSS custom properties and a typed
+JavaScript manifest. Light and dark modes are included.
+
+```bash
+npm install @quieto/design-tokens
+```
+
+## Use the CSS
+
+Load the stylesheet **once**, at the top of your app:
+
+```js
+// From JavaScript, in any bundler (Vite, webpack, Next.js, …)
+import '@quieto/design-tokens/css';
+```
+
+```css
+/* Or from a stylesheet, if your bundler resolves @import from node_modules */
+@import '@quieto/design-tokens/css';
+```
+
+Then use the variables:
+
+```css
+.card {
+  color: var(--qds-semantic-color-content-default);
+  background: var(--qds-semantic-color-background-subtle);
+  border-radius: var(--qds-semantic-radius-primary);
+  padding: var(--qds-spacing-400);
+  box-shadow: var(--qds-semantic-elevation-default);
+}
+```
+
+Custom properties inherit, including into shadow DOM, so one stylesheet on the document styles
+everything below it.
+
+## Light and dark mode
+
+`@quieto/design-tokens/css` contains both modes. With no attribute set, it follows the operating
+system's `prefers-color-scheme`. Set `data-theme` on `<html>` to override it:
+
+| Markup | Result |
+| --- | --- |
+| `<html>` | Follows the OS setting |
+| `<html data-theme="dark">` | Dark, whatever the OS says |
+| `<html data-theme="light">` | Light, whatever the OS says |
+
+> **Set `data-theme` on `<html>` only.** A nested element such as `<section data-theme="dark">`
+> gets dark *semantic* tokens but light *component* tokens, so its components render in the wrong
+> mode. Component tokens reference semantic tokens, and a reference is resolved on the element
+> where the variable is declared — `:root` — not where it is used. Scoped theming for a section of
+> a page is not supported yet.
+
+If your product ships only one mode, import that file instead. Each one is complete on its own:
+
+```js
+import '@quieto/design-tokens/css/light';
+// or
+import '@quieto/design-tokens/css/dark';
+```
+
+## Which tokens to use
+
+Every variable belongs to one of three tiers, and each tier references only the tier below it.
+
+| Tier | Example | Use it for |
+| --- | --- | --- |
+| Primitive | `--qds-color-blue-600` | Raw values. Rarely used directly — they do not change with the theme. |
+| Semantic | `--qds-semantic-color-background-primary-rest` | **Product code.** These carry meaning and switch with the theme. |
+| Component | `--qds-component-button-primary-color-background-rest` | Restyling a QDS component. Override the variable instead of writing new CSS. |
+
+Reach for a **semantic** token first. A primitive like `--qds-color-blue-600` stays blue in dark
+mode; `--qds-semantic-color-background-primary-rest` switches correctly.
+
+Names follow a grammar — `{prefix}-{tier}-{category}-{property}-{role}-{state}` for semantic
+tokens — which is checked at build time. The full specification, with every allowed category,
+role and state, is in
+[`docs/nomenclature.md`](https://github.com/dillonschultz93/qds/blob/main/packages/design-tokens/docs/nomenclature.md).
+
+## Use the tokens from JavaScript
+
+```js
+import { tokens, byName, cssVar } from '@quieto/design-tokens';
+
+const primary = byName['qds-semantic-color-background-primary-rest'];
+primary.modes.light; // '#2563eb'
+primary.modes.dark; // '#3b82f6'
+primary.referenceNames.light; // ['qds-color-blue-600']
+
+cssVar(primary.name); // 'var(--qds-semantic-color-background-primary-rest)'
+```
+
+Each token has `name`, `path`, `type`, `tier`, `set`, `description`, its resolved value in each
+mode (`modes`), what it references (`references`, `referenceNames`), and `modeInvariant`. Types
+are included.
+
+The manifest is a single 294 kB module, and importing anything from it includes all of it. If you
+only need the CSS variables, you don't need to import JavaScript at all.
+
+## Everything the package exports
+
+| Import | Contents |
+| --- | --- |
+| `@quieto/design-tokens` | Typed token manifest: `tokens`, `byName`, `cssVar` |
+| `@quieto/design-tokens/css` | All tokens, light and dark |
+| `@quieto/design-tokens/css/light` | All tokens, light only |
+| `@quieto/design-tokens/css/dark` | All tokens, dark only |
+| `@quieto/design-tokens/nomenclature` | The naming grammar's vocabularies, as data |
+| `@quieto/design-tokens/tokens.json` | The Tokens Studio source file. References are **unresolved** (`{color.blue.600}`); for tooling, not runtime use. |
+
+## Fonts are not included
+
+The type tokens name these families but do not load them:
+
+- `--qds-typography-font-family-sans`: Inter, then `system-ui`
+- `--qds-typography-font-family-mono`: JetBrains Mono, then `ui-monospace`
+
+Load Inter and JetBrains Mono yourself, or accept the system fallbacks.
+
+## Compatibility
+
+- **Modules:** ES modules. `require()` also works on Node versions that can require ES modules
+  (20.19 and later, 22.12 and later).
+- **TypeScript:** types resolve with `moduleResolution` set to `bundler`, `node16`, or `node`.
+- **No runtime dependencies.**
+
+## Versioning
+
+This package is pre-1.0, so **token names can change in any minor release.** On `0.x`, npm's
+caret range does not cross a minor version: `^0.1.0` installs `0.1.x` but never `0.2.0`, so a
+rename will not reach you without an explicit upgrade. The
+[changelog](https://github.com/dillonschultz93/qds/blob/main/packages/design-tokens/CHANGELOG.md)
+lists every rename.
+
+## License
+
+MIT