@gusnips/tokens 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+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

@@ -0,0 +1,85 @@
+# @gusnips/tokens
+
+The colour names a Tailwind 4 app uses, and the dark-mode switch behind them. You bring the
+colours.
+
+```bash
+bun add @gusnips/tokens
+```
+
+```css
+@import "tailwindcss";
+@import "@gusnips/tokens/index.css";
+```
+
+Two lines, and you can write `bg-card text-card-foreground` anywhere. It renders in light mode
+and in dark mode, and no component ever writes a `dark:` variant.
+
+## The mechanism
+
+Twenty names — `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`,
+`accent`, `destructive`, their `-foreground` pairs, plus `border`, `input`, `ring` and `scrim`.
+
+Dark mode rebinds **the same names** under a `.dark` class. `bg-card` is one utility that
+resolves to a different colour below a `.dark` ancestor. That is the whole trick.
+
+## Your colours
+
+The values that ship are a plain grey scale — readable, and deliberately characterless, so the
+app looks like nothing until you decide what it looks like. Override after the import, and set
+both halves:
+
+```css
+@theme {
+  --color-primary: #7c3aed;
+}
+.dark {
+  --color-primary: #a78bfa;
+}
+```
+
+Skip the second line and your daytime purple stays on screen at night.
+
+## Two names you cannot pick freely
+
+A build check measures both, so a bad value fails your build instead of reaching someone.
+
+- **`--color-input` needs 3:1 against `--color-background`.** It is a field border, and WCAG
+  1.4.11 asks 3:1 of anything that outlines a control. This is the one people miss: a grey
+  picked to sit nicely next to `--color-border` will not clear it. One codebase this came from
+  pointed `input` at its divider grey — 1.6:1 — so every text field in two apps had a border
+  some people cannot see.
+- **`--color-primary` needs its own dark value.** Holding one brand colour across both modes is
+  the trap. A fill chosen against a white page is dark, and on a near-black card it lands _on_
+  the 3:1 line instead of clear of it. Lift it for dark, and flip `--color-primary-foreground`
+  with it — which is why nothing in this family writes `text-white`.
+
+## What is not here
+
+Fonts, shadows, radii, type scale, motion. Radii and type sizes already have Tailwind's own
+`--radius-*` and `--text-*` names, so retune those in your `@theme` and every `rounded-lg` in
+every component follows. The rest is what your product looks like, and it stays in your product.
+
+One trap worth knowing before you write your own `@theme`: **`--duration-*` is not a Tailwind
+namespace.** `--duration-standard: 250ms` compiles to no utility at all, so `duration-standard`
+in a `className` is dead text and the transition quietly runs at Tailwind's default. `--ease-*`
+beside it _does_ work, which is what hides it — the easing lands, the duration does not. Write
+`duration-250`, or keep the token and put `transition-duration: var(--duration-standard)` in a
+real rule. One codebase had 61 of these.
+
+## The base rules
+
+`index.css` also brings a handful of rules that every app needs and nobody remembers:
+
+- one `:focus-visible` outline, drawn with `--color-ring`, so it follows your theme into dark
+- `cursor: pointer` on buttons, which browsers do not give you
+- `color-scheme`, which stops a two-tone seam where a phone toolbar retracts
+- reduced motion clamped to `0.01ms` rather than `none`, so animations still land on their end
+  pose instead of never appearing — including the two delay properties, which are the half
+  people forget
+- a thin scrollbar whose thumb reads `--color-input`, and `.scrollbar-none` for a tab strip
+
+Want them separately? `@gusnips/tokens/theme.css` is the names with no rules,
+`@gusnips/tokens/base.css` the rules with no names.
+
+MIT · part of [frontkit](https://github.com/gusnips/frontkit)

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@gusnips/tokens",
+  "version": "0.1.0",
+  "description": "One Tailwind 4 @theme file: the semantic token contract, the dark-mode mechanism, and the base rules every app needs. Colours stay per-brand.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/frontkit/tree/main/tokens#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/frontkit/issues"
+  },
+  "exports": {
+    "./theme.css": "./src/theme.css",
+    "./base.css": "./src/base.css",
+    "./index.css": "./src/index.css"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "tailwindcss",
+    "tailwind-v4",
+    "design-tokens",
+    "theme",
+    "dark-mode",
+    "css"
+  ],
+  "scripts": {
+    "build": "bun run scripts/compile-check.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun run scripts/compile-check.ts",
+    "lint": "eslint scripts",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.3.3",
+    "@types/node": "^24.12.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/frontkit.git",
+    "directory": "tokens"
+  }
+}

package/src/base.css

@@ -0,0 +1,121 @@
+/*
+ * The base rules every app needs and nobody remembers to write.
+ *
+ * Each rule below is here because a product shipped without it and something broke. No
+ * colours and no brand: every value reads a token from theme.css, so import that first —
+ * or import index.css, which does both in the right order.
+ */
+
+@layer base {
+  /* The browser paints two areas itself: the overscroll rubber-band, and the strip a
+     100svh surface leaves uncovered when a mobile toolbar retracts. With no explicit
+     `color-scheme` it paints them its own default near-black, a hair off our surface —
+     a hard two-tone seam across every full-height loading and error screen. Painting
+     `html` (not just `body`) and declaring the scheme makes those UA-painted areas match.
+     `color-scheme` also fixes form controls, scrollbars and the caret, which is the
+     second half of the same win. */
+  html {
+    color-scheme: light;
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+
+  /* Matches wherever the class lives. Products put it on <html>, which is what makes the
+     canvas follow; on <body> it still corrects controls and scrollbars in the subtree. */
+  .dark {
+    color-scheme: dark;
+  }
+
+  /* A browser's default cursor for <button> is the arrow — links get the hand for free,
+     buttons never do — and Tailwind's preflight does not say otherwise. So nothing built
+     out of a Button primitive read as clickable on hover. Saying it once here beats
+     sprinkling `cursor-pointer` across every primitive and every call site.
+     In `@layer base` on purpose: cursor utilities live in the utilities layer, which the
+     cascade puts after base, so a component that deliberately asks for `cursor-default`
+     or `cursor-not-allowed` on an enabled button still wins. `:not(:disabled)` leaves the
+     disabled cursor alone, since that element sets its own. */
+  button:not(:disabled),
+  [role="button"]:not([aria-disabled="true"]) {
+    cursor: pointer;
+  }
+
+  /* One focus ring for the whole app, drawn with the ring token so it follows the theme
+     into dark mode with no second rule. No `border-radius` here: an outline already
+     traces the element's own radius, and forcing a value squares a pill or a segmented
+     control back into a rectangle. */
+  :focus-visible {
+    outline: 2px solid var(--color-ring);
+    outline-offset: 2px;
+  }
+
+  /* The ring reaches text fields too, and nothing here strips it from them. That is
+     deliberate, and it is the one donor rule that had to INVERT on the way into a package.
+     The app it came from follows this with `outline: none` on every input, textarea, select
+     and combobox, because its own fields each draw a border-plus-ring on focus and the
+     global outline landed on top as a doubled, heavy frame. There, removing it is a fix.
+     Here it would be the reverse: we add a ring the adopter never had, then take it away
+     again from exactly the elements that most need one. An app with plain `<input>`s would
+     import this file and come out with no keyboard focus indicator on any field — a WCAG
+     2.4.7 failure introduced by us, in an app that was fine before. A shared layer does not
+     get to make that trade, and a comment telling adopters to put the ring back is not a
+     fix, because it only works for the ones who read it.
+     A control that genuinely draws its own focus treatment opts out on itself, with
+     `focus-visible:outline-none` on the element. Utilities sit in a later cascade layer
+     than base, so it wins with no specificity fight, and the opt-out stays local to the one
+     component that earned it. */
+
+  /* A thin scrollbar, because the OS default is a wide light bar that stays light on a
+     dark app. The thumb reads `--color-input`, the one token defined to clear 3:1 against
+     the surface behind it — exactly what a scrollbar needs — and it is rebound in `.dark`,
+     so the thumb follows the theme without a second rule.
+     6px is a choice, not a contract — override the width in your own stylesheet if your
+     app wants a chunkier bar. What is load-bearing is the token the thumb reads.
+     WebKit pseudo-elements only, deliberately: setting the standard `scrollbar-width`
+     makes Chrome ignore these rules entirely, so asking for both gets neither. */
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  ::-webkit-scrollbar-thumb {
+    background: var(--color-input);
+    border-radius: 3px;
+  }
+}
+
+@layer utilities {
+  /* Hide the bar, keep the scroll — for a tab strip or filter row that scrolls sideways,
+     where the scrollbar is chrome nobody drags. Here `scrollbar-width` is the right tool
+     and it deliberately overrides the rule above; the WebKit line covers Safari before
+     18.2, which does not support the standard property. */
+  .scrollbar-none {
+    scrollbar-width: none;
+  }
+
+  .scrollbar-none::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+/* Reduced motion. Clamped to 0.01ms rather than `none` so every animation still FIRES and
+   lands on its end pose — an element whose visible state is a keyframe's `to` block would
+   otherwise never appear at all.
+   The two delay properties are the half that is easy to miss: without them a staggered
+   list still waits out its full stagger before anything shows up, which is the delay with
+   none of the motion that explained it. One of the three donor themes clamped the
+   durations and forgot the delays. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    animation-delay: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+    transition-delay: 0.01ms !important;
+  }
+}

package/src/index.css

@@ -0,0 +1,46 @@
+/*
+ * The tokens and the base rules together. Import this unless you have a reason not to.
+ *
+ * An app entry is three lines:
+ *
+ *   @import "tailwindcss";
+ *   @import "@gusnips/tokens/index.css";
+ *   @source "../../../packages/ui/src";   // one per package Tailwind must scan for classes
+ *
+ * Then your own colours, after those. Override a name in `@theme` for light and in `.dark`
+ * for dark — both halves, every time, or the light value stays on screen at night:
+ *
+ *   @theme { --color-primary: #7c3aed; }
+ *   .dark  { --color-primary: #a78bfa; }
+ *
+ * That is two lines, and it changes every component that ever wrote `bg-primary`.
+ *
+ * Keep this import AFTER `@import "tailwindcss"`. It uses `@theme`, `@layer` and
+ * `@custom-variant`, and Tailwind only understands those once it has been imported.
+ *
+ * You do not need to declare `@custom-variant dark` yourself — theme.css ships it.
+ *
+ * Take the halves separately if you need to: `@gusnips/tokens/theme.css` is the tokens
+ * with no rules, `@gusnips/tokens/base.css` the rules with no tokens.
+ *
+ * Not here, on purpose: fonts, shadows, radii, a type scale, motion, keyframes. Radii,
+ * type sizes and easings already have Tailwind's own `--radius-*`, `--text-*` and
+ * `--ease-*` names — retune those in your `@theme` and every `rounded-lg` in every
+ * component follows. The rest is what your product looks like, and it stays in your
+ * product.
+ *
+ * Migrating a theme that has its own radii: keep `--radius-sm/md/lg/xl` and retune the
+ * values — they are already Tailwind's names. Drop `--radius-full` and `--radius-pill`.
+ * `rounded-full` is a built-in utility that needs no token at all, and it resolves to
+ * `calc(infinity * 1px)`, which stays round on an element taller than the `9999px` both
+ * donor themes redefined it to. A theme that spells it `pill` renames every
+ * `rounded-pill` to `rounded-full` and deletes the token.
+ *
+ * One trap worth knowing before you write your own `@theme`: `--duration-*` is NOT a
+ * Tailwind namespace. `duration-standard` compiles to nothing at all, silently, and the
+ * transition falls back to 150ms. `duration-250` works; so does `var(--duration-standard)`
+ * inside a hand-written rule. The compile check pins this so nobody rediscovers it.
+ */
+
+@import "./theme.css";
+@import "./base.css";

package/src/theme.css

@@ -0,0 +1,117 @@
+/*
+ * The colour contract, and the dark-mode mechanism.
+ *
+ * Twenty names. Nineteen of them were already defined, independently, in three separate
+ * product themes — that agreement is what makes this a contract rather than a preference.
+ * A component writes `bg-card text-card-foreground` once and renders correctly in both
+ * modes, in every product that imports this file.
+ *
+ * Dark mode is class-strategy: the SAME names are rebound under `.dark`, so `bg-card`
+ * resolves differently below a `.dark` ancestor and no component ever writes a `dark:`
+ * variant. That is the entire mechanism, and it is the reason the names are worth sharing.
+ * The alternative one product tried — a parallel `--color-dark-*` namespace — makes every
+ * component spell out both halves, which is a `dark:` variant with extra steps.
+ *
+ * The VALUES are placeholders: a plain grey scale, accessible and deliberately
+ * characterless. A product overrides them in its own `@theme` block AFTER importing this
+ * one. Colour is where a product lives; it does not belong in a shared package.
+ *
+ * Two traps, both of which cost real time to find:
+ *   - Do NOT change this to `@theme inline`. Inline bakes each value into the utility, and
+ *     the `.dark` rebinding below silently stops working.
+ *   - A name added here must be added to `.dark` too. Forgetting leaves one colour stuck at
+ *     its light value in dark mode, on one screen, which is how a theme rots. The compile
+ *     check fails on that.
+ */
+
+/* `:where()` keeps the variant at zero specificity, so `dark:bg-card` and `bg-card` weigh
+   the same and source order decides — the ordinary Tailwind behaviour every other variant
+   has. Without it the dark variant would quietly outrank hover and focus styles. */
+@custom-variant dark (&:where(.dark, .dark *));
+
+@theme {
+  /* ─── Light ───
+     Contrast measured, not guessed: foreground on background 17.2:1, muted-foreground on
+     background 7.5:1 and on muted 7.2:1, every `-foreground` on its own surface above
+     14:1. Two of those are floors the compile check enforces — see `input` below. */
+  --color-background: #fafafa;
+  --color-foreground: #171717;
+  --color-card: #ffffff;
+  --color-card-foreground: #171717;
+  --color-popover: #ffffff;
+  --color-popover-foreground: #171717;
+  --color-primary: #171717;
+  --color-primary-foreground: #fafafa;
+  --color-secondary: #f5f5f5;
+  --color-secondary-foreground: #171717;
+  --color-muted: #f5f5f5;
+  --color-muted-foreground: #525252;
+  /* `accent` is the NEUTRAL highlight — a menu row under the cursor, a hovered list item.
+     Brand tinting is always explicit, never the ambient default. Two of the three donor
+     themes say this in their own words, and the third had to fix it later. */
+  --color-accent: #e5e5e5;
+  --color-accent-foreground: #171717;
+  /* The one placeholder that is not grey. `destructive` is a MEANING, not a brand choice:
+     a grey delete button is indistinguishable from a secondary one, so a product that
+     never overrides this still gets a warning that reads as a warning. 4.8:1 under white. */
+  --color-destructive: #dc2626;
+  --color-destructive-foreground: #ffffff;
+  --color-border: #e5e5e5;
+  /* `input` is a control BOUNDARY, not decoration, so 3:1 against `--color-background` is
+     a FLOOR and not a preference (WCAG 1.4.11). The compile check fails below it, in both
+     modes. If you override this token, measure it: a grey picked to sit nicely beside
+     `border` will not clear 3:1, which is exactly how one donor ended up pointing `input`
+     at the same rung it uses for a passive divider — 1.6:1 in light, 2.2:1 in dark, so
+     every field border in two of its apps is invisible to somebody.
+     `border` has no floor. It is a hairline between two surfaces, and nothing depends on
+     seeing it; that is why the two tokens exist separately and why this one is so much
+     darker. Here: 3.2:1 on background, 3.4:1 on card. */
+  --color-input: #8c8c8c;
+  --color-ring: #171717;
+  /* What a dialog dims the page with. A token rather than `black/40`, because the two
+     modes need different scrims: over a light ground a wash of ink reads as shade, and
+     over a dark ground the same wash reads as nothing at all. */
+  --color-scrim: rgb(23 23 23 / 0.5);
+}
+
+/*
+ * Dark. Stays after `@theme` on purpose: `@theme` compiles to a `:root` rule, and `:root`
+ * and `.dark` carry equal specificity, so source order is the only thing making the dark
+ * values win.
+ *
+ * Elevation here is lightness, not shadow — a drop shadow barely reads on a near-black
+ * ground. background → card → accent climb in even steps so a popover lifts off the page
+ * without needing one.
+ */
+.dark {
+  --color-background: #0a0a0a;
+  --color-foreground: #fafafa;
+  --color-card: #171717;
+  --color-card-foreground: #fafafa;
+  --color-popover: #171717;
+  --color-popover-foreground: #fafafa;
+  /* Primary LIFTS for dark, and its label flips dark with it. Copy the strategy, not the
+     greys. The tempting version — hold one brand colour across both modes, keep a white
+     label — is the trap: a fill chosen to look right on a white page is dark, and on a
+     near-black card it lands ON the 3:1 a UI component needs rather than clear of it. One
+     donor's held violet measures 3.08:1 against its own dark card, which passes with 0.08
+     to spare; the donor that lifts the same kind of hue for dark measures 6.6:1. The
+     margin is the whole difference, and it disappears the first time someone lightens a
+     card. The label must flip because a lifted fill is light — white on it is unreadable. */
+  --color-primary: #fafafa;
+  --color-primary-foreground: #171717;
+  --color-secondary: #262626;
+  --color-secondary-foreground: #fafafa;
+  --color-muted: #262626;
+  --color-muted-foreground: #a3a3a3;
+  --color-accent: #333333;
+  --color-accent-foreground: #fafafa;
+  /* Inverted, not darkened: a saturated red on a near-black ground is unreadable, so the
+     fill lifts and the label goes dark. 5.8:1. */
+  --color-destructive: #f87171;
+  --color-destructive-foreground: #450a0a;
+  --color-border: #262626;
+  --color-input: #6b6b6b; /* 3.7:1 on background, 3.4:1 on card */
+  --color-ring: #fafafa;
+  --color-scrim: rgb(0 0 0 / 0.65);
+}