@codenhub/styles 0.7.0 → 0.9.0

package/{dist/tw → tw}/index.css

@@ -1,7 +1,7 @@
 @import "tailwindcss";
 
-/* The build has no markup to scan, so Tailwind's automatic content detection
-   sees only this package's own files. The `src/` scan is load-bearing: it is
+/* The compiled build has no markup to scan, so Tailwind's automatic content
+   detection sees only this package's own files. The `src/` scan is load-bearing: it is
    how the composition utilities (`box`, `surface`, `text-control`,
    `input-group`) are emitted as standalone rules, so
    `source(none)` is not an option. Tailwind utility names that collide with a
@@ -9,18 +9,20 @@
    `transition`, `transform`, `container`) do not emit, verified against
    Tailwind 4.3.2; `tests/integration/exports.test.ts` guards it.
 
-   The `@source not` lines keep everything that is not `src/` out of the scan:
+   The `@source not` lines keep the build command's TypeScript in `src/cli/`, whose
+   prose once shipped as `.relative`, and everything that is not `src/` out of the scan:
    the sibling app and fixture directories, the `docs/` tree, the build scripts,
    and the root prose, data, config, and license files. Without them a class
    name or `--color-*` reference that appears only in a documentation example
    ships as real CSS -- the license's "contents" once shipped as
    `.contents{display:contents}`.
    `exports.test.ts` guards it. `scripts/build-tw.mjs` strips these lines from
-   the `dist/tw/` copy, where they resolve to nothing and the `/tw` consumer
-   scans their own tree. */
+   the `tw/` copy, where they have no job: the `/tw` consumer scans their own
+   tree. */
 
 @import "./theme.css";
-@import "./typography.css";
-@import "./utilities/index.css";
-@import "./components/index.css";
-@import "./reset.css";
+/* No `typography.css` here: `components/rules.css` brings its rules, and a
+   second route to a `@utility` stacks its body. */
+@import "./utilities/rules.css";
+@import "./components/rules.css";
+@import "./reset.rules.css";

package/tw/index.d.ts

@@ -0,0 +1 @@
+export {};

package/tw/intent.css

@@ -0,0 +1,312 @@
+/* The intent classes are `@utility` rules in `utilities.families`, so `@apply`
+   and Tailwind's variants reach them while every rule written straight into
+   `utilities` still beats them; the floor and the resets are plain rules in
+   `components`, below both. See docs/internal/model.md#cascade-layers. */
+
+/* An intent maps one colour family onto seven shared slots and nothing else.
+   It does not cascade: the reset at the bottom redeclares the neutral defaults
+   at every component's own root, so a `.success` container cannot recolour a
+   nested destructive button while `.btn.success` still wins. Every intent writes
+   every slot, `--intent-fill-max` included -- omitting it inherits the reset's
+   neutral cap, and `tests/integration/registry.test.ts` fails the build on one
+   that does. Neutral maps `--intent-subtle` to `--color-surface` (the tone
+   tooltips, key caps, code and table heads sit on) and `--intent-border` to
+   `--ui-ink` (how an aesthetic restates the neutral line without naming one). */
+
+/* The same neutral values, at the root. This is the floor: an element that
+   carries no intent class and matches none of the resets below -- a component
+   `@apply`-ed onto a selector the package does not name, a bare `<code>` with
+   no native stylesheet loaded -- still composes against a real colour instead
+   of an undefined one that collapses its `color-mix()` to nothing. It is not
+   the barrier. `.neutral` and both resets below still write these slots on the
+   element itself, which is a matching rule and so beats this inherited value --
+   that is what stops a `.success` container's intent reaching a component
+   nested under it. An intent class on the element beats both. Values track
+   `.neutral` slot for slot; `registry.test.ts` fails the build on drift.
+
+   Except `--intent-border`, which is left undeclared here. Neutral's line is
+   `--ui-ink`, which an aesthetic sets on its own class, never on `:root`, so
+   resolved here it was always the theme's grey: a bare `box` under
+   `.neobrutalism` drew a grey line and a grey slab beside a `.neutral`
+   sibling's black ink. Its readers -- `box`, `.quote`, `.data-table` -- fall
+   back to the same chain on the element instead. */
+@layer components {
+  :root {
+    --intent-color: var(--color-text);
+    --intent-contrast: var(--color-text-contrast);
+    --intent-hover: var(--color-text-hover);
+    --intent-strong: var(--color-text-strong);
+    --intent-subtle: var(--color-surface);
+    --intent-fill-max: 20%;
+  }
+}
+
+/* Neutral stops its fill short: its colour is the page's ink, so a full fill is
+   a slab and `.neutral.solid` would be pixel-for-pixel `.primary.solid`. 20% is
+   chosen against `.soft`'s 12% -- a step past the tint, not a repeat.
+   `--intent-contrast` stays the page colour; a `.neutral.solid` badge's ink is
+   `box`'s question, answered by the same `--ui-fg-on-fill` cap. Pointing this
+   slot at `--color-text` renders a checked neutral checkbox black-on-black. */
+@utility neutral {
+  @layer families {
+    --intent-color: var(--color-text);
+    --intent-contrast: var(--color-text-contrast);
+    --intent-hover: var(--color-text-hover);
+    --intent-strong: var(--color-text-strong);
+    --intent-subtle: var(--color-surface);
+    --intent-border: var(--ui-ink, var(--color-border));
+    --intent-fill-max: 20%;
+  }
+}
+
+@utility primary {
+  @layer families {
+    --intent-color: var(--color-primary);
+    --intent-contrast: var(--color-primary-contrast);
+    --intent-hover: var(--color-primary-hover);
+    --intent-strong: var(--color-primary-strong);
+    --intent-subtle: var(--color-primary-subtle);
+    --intent-border: var(--color-primary);
+    --intent-fill-max: 100%;
+    /* With more contrast asked for, an intent's line is its strong tone, in
+       this and every intent below. `box` fades a line by the fill under it, so
+       on a soft fill the resting tone drew at 2.4:1 for warning in light and
+       2.9:1 for success in dark. See docs/accessibility.md. */
+    @media (prefers-contrast: more) {
+      --intent-border: var(--color-primary-strong);
+    }
+  }
+}
+
+@utility secondary {
+  @layer families {
+    --intent-color: var(--color-accent);
+    --intent-contrast: var(--color-accent-contrast);
+    --intent-hover: var(--color-accent-hover);
+    --intent-strong: var(--color-accent-strong);
+    --intent-subtle: var(--color-accent-subtle);
+    --intent-border: var(--color-accent);
+    --intent-fill-max: 100%;
+    @media (prefers-contrast: more) {
+      --intent-border: var(--color-accent-strong);
+    }
+  }
+}
+
+@utility success {
+  @layer families {
+    --intent-color: var(--color-success);
+    --intent-contrast: var(--color-success-contrast);
+    --intent-hover: var(--color-success-hover);
+    --intent-strong: var(--color-success-strong);
+    --intent-subtle: var(--color-success-subtle);
+    --intent-border: var(--color-success);
+    --intent-fill-max: 100%;
+    @media (prefers-contrast: more) {
+      --intent-border: var(--color-success-strong);
+    }
+  }
+}
+
+@utility warning {
+  @layer families {
+    --intent-color: var(--color-warning);
+    --intent-contrast: var(--color-warning-contrast);
+    --intent-hover: var(--color-warning-hover);
+    --intent-strong: var(--color-warning-strong);
+    --intent-subtle: var(--color-warning-subtle);
+    --intent-border: var(--color-warning);
+    --intent-fill-max: 100%;
+    @media (prefers-contrast: more) {
+      --intent-border: var(--color-warning-strong);
+    }
+  }
+}
+
+@utility destructive {
+  @layer families {
+    --intent-color: var(--color-destructive);
+    --intent-contrast: var(--color-destructive-contrast);
+    --intent-hover: var(--color-destructive-hover);
+    --intent-strong: var(--color-destructive-strong);
+    --intent-subtle: var(--color-destructive-subtle);
+    --intent-border: var(--color-destructive);
+    --intent-fill-max: 100%;
+    @media (prefers-contrast: more) {
+      --intent-border: var(--color-destructive-strong);
+    }
+  }
+}
+
+@utility info {
+  @layer families {
+    --intent-color: var(--color-info);
+    --intent-contrast: var(--color-info-contrast);
+    --intent-hover: var(--color-info-hover);
+    --intent-strong: var(--color-info-strong);
+    --intent-subtle: var(--color-info-subtle);
+    --intent-border: var(--color-info);
+    --intent-fill-max: 100%;
+    @media (prefers-contrast: more) {
+      --intent-border: var(--color-info-strong);
+    }
+  }
+}
+
+/* Every component resolves the neutral defaults at its own root, at zero
+   specificity, so an intent class on the element wins while an inherited value
+   loses -- the one rule that lets every component drop its per-intent branches.
+   This list and the one in `native.css` are the package's only hand-maintained
+   selector lists; `tests/integration/registry.test.ts` fails the build on a
+   registry component missing from either. `.text-control` and `.surface` are on
+   it though they are not components: both are documented as typeable on their
+   own, and a bare `<div class="surface">` with no intent resolved computes a
+   transparent background and a zero-width border -- `box` collapses. A
+   consumer's `@apply surface` or `@apply text-control` is not on it; each
+   utility carries its own copy for that element, excluding the classes here
+   that apply it, and `registry.test.ts` fails when that exclusion list drifts
+   from the classes that do. See docs/internal/model.md#what-apply-carries. */
+@layer components {
+  :where(
+    .btn,
+    .ipt,
+    .text-control,
+    .surface,
+    .textarea,
+    .select,
+    .input-group,
+    .checkbox,
+    .radio,
+    .switch,
+    .card,
+    .panel,
+    .alert,
+    .data-table,
+    .pre,
+    .quote,
+    .tooltip-bubble,
+    .tooltip-icon,
+    .badge,
+    .kbd,
+    .code,
+    .skeleton,
+    .progress,
+    .divider
+  ) {
+    --intent-color: var(--color-text);
+    --intent-contrast: var(--color-text-contrast);
+    --intent-hover: var(--color-text-hover);
+    --intent-strong: var(--color-text-strong);
+    --intent-subtle: var(--color-surface);
+    --intent-border: var(--ui-ink, var(--color-border));
+    --intent-fill-max: 20%;
+  }
+}
+
+/* The six text controls take a heavier line than everything else that rests on
+   the shared neutral. A card, a table or a divider sits on a filled surface or
+   separates content that identifies itself; a text control at rest is a
+   transparent box whose only mark is its border, and WCAG 1.4.11 asks that
+   border for 3:1. `--color-border` gives it 1.42:1.
+
+   Declared here at zero specificity for the same reason the indicators below
+   are: written inside `@utility text-control` it would land in `utilities`,
+   above every intent class in `components`, and overrule `.primary` on the
+   element. Written as a plain class list it would carry 0-1-0 and, being later
+   in the stylesheet, beat `.primary` the same way. Either would make every
+   colored control draw a grey line; `:where()` keeps it under both. The copy
+   `text-control` carries for `@apply` does sit in `utilities`, and is safe
+   there only because it never matches an element with an intent class.
+
+   An aesthetic reaches this line through `--ui-control-ink` first, then its
+   `--ui-ink`: the theme keeps a control border apart from a surface border, and
+   an aesthetic whose neutral line suits a pane but not a control's boundary --
+   `.glass`'s white hairline, `.chunky-tile`'s tile grey -- names a control line
+   of its own. See docs/internal/model.md#presentation.
+
+   The second selector is the tooltip bubble's below, for the same reason:
+   `.neutral` carries 0-1-0 and beat `:where()`, so a `.neutral` field under
+   `.glass` drew the pane's hairline while an unclassed one drew the control
+   line, and writing the intent out changed the box. */
+@layer components {
+  :where(.text-control, .ipt, .textarea, .select, .input-group, .checkbox, .radio, .switch) {
+    --intent-border: var(--ui-control-ink, var(--ui-ink, var(--color-control-border)));
+  }
+}
+
+/* The `.neutral` arm sits beside the class it has to outrank, which is in
+   `utilities.families`; from `components` it would lose to it. */
+@layer utilities.families {
+  :is(.text-control, .ipt, .textarea, .select, .input-group, .checkbox, .radio, .switch).neutral {
+    --intent-border: var(--ui-control-ink, var(--ui-ink, var(--color-control-border)));
+  }
+}
+
+/* A table's lines -- its frame, head rule, and row rules -- are drawn on a
+   plate, not at a pane's edge against the backdrop, so an aesthetic whose
+   neutral line is a highlight names a rule line of its own: glass's white
+   hairline vanishes on the table's light plate. Neutral only, and `.neutral`
+   included, the way the control line above is, and a `.neutral` row in a
+   table of another intent, which draws its rules as a neutral table does. */
+@layer components {
+  :where(.data-table) {
+    --intent-border: var(--ui-rule-ink, var(--ui-ink, var(--color-border)));
+  }
+}
+
+@layer utilities.families {
+  :is(.data-table, .data-table tr).neutral {
+    --intent-border: var(--ui-rule-ink, var(--ui-ink, var(--color-border)));
+  }
+}
+
+/* The bubble a tooltip draws is the one plate in the package that is chosen
+   rather than composed, so it resolves the no-intent case onto its own pair
+   instead of the shared neutral -- see `--color-tooltip` in `theme.css`.
+
+   The cap goes with it. Neutral stops its fill at 20% because its colour is the
+   page's ink; `--color-tooltip` is a plate rather than an ink, so a full fill
+   of it is the plate and there is nothing to stop short of. `--intent-subtle`
+   stays the surface token, the tone every other unclassed component sits on.
+   `.tooltip-icon` is a separate element that never fills past `0%`, so the
+   generic neutral reset above is enough for it.
+
+   Two selectors, so `none` and `neutral` agree. `:where()` loses to any intent
+   class, so `.tooltip-bubble.primary` still floods with primary;
+   `.tooltip-bubble.neutral` carries 0-2-0 and beats `.neutral`, so writing the
+   intent out gives the same bubble as writing nothing. */
+@layer components {
+  :where(.tooltip-bubble) {
+    --intent-color: var(--color-tooltip);
+    --intent-contrast: var(--color-tooltip-contrast);
+    --intent-hover: var(--color-tooltip);
+    --intent-strong: var(--color-tooltip-contrast);
+    --intent-subtle: var(--color-surface);
+    --intent-border: var(--ui-ink, var(--color-border));
+    --intent-fill-max: 100%;
+  }
+}
+
+@layer utilities.families {
+  .neutral.tooltip-bubble {
+    --intent-color: var(--color-tooltip);
+    --intent-contrast: var(--color-tooltip-contrast);
+    --intent-hover: var(--color-tooltip);
+    --intent-strong: var(--color-tooltip-contrast);
+    --intent-subtle: var(--color-surface);
+    --intent-border: var(--ui-ink, var(--color-border));
+    --intent-fill-max: 100%;
+  }
+}
+
+/* Indicators take the color they sit in rather than the shared neutral, so a
+   skeleton inside filled or colored content still matches it. It has to be
+   declared here at zero specificity: written in the component's own block it
+   would carry 0-1-0 and, being later in the stylesheet, beat `.success` --
+   which silently makes every indicator ignore every intent class. */
+@layer components {
+  :where(.skeleton, .progress, .divider) {
+    --intent-color: currentColor;
+    --intent-border: currentColor;
+  }
+}

package/tw/modifiers.css

@@ -0,0 +1,127 @@
+/* The component modifiers: density, direction, width, padding, shape, and the
+   two progress states. Each is a utility in `utilities.families`, as the
+   classes in `presentation.css` are, so `@apply stack tight` and `md:tight`
+   work, and a consumer's component takes a modifier the way a shipped one
+   does.
+
+   A modifier cannot say what it changes, because each component answers it
+   with its own values -- `p-xs` is 0.5rem on a card and 0.25rem on a panel --
+   so it raises a flag and the component reads it, as `sm` and `lg` do in
+   `size.css`. The flag is a space toggle: unset it is guaranteed-invalid, so
+   `--_tight-gap: var(--_m-tight) 0.5rem` is invalid too and the
+   `var(--_tight-gap, ...)` that reads it takes its fallback; set, it is
+   empty, and the same line computes to `0.5rem`.
+
+   On an element that reads none of them a flag is a custom property nothing
+   uses, so a page's own `.active` or `.wide` class is not restyled by these.
+
+   The flags are not registered, unlike the size flags: a `@property` rule
+   ships in every build, used or not, and there are fifteen of these. They
+   inherit instead, and each component that reads one restates it `initial`
+   on itself at zero specificity -- see `--_m-` in the component files -- so a
+   `.card.p-xs` does not shrink the padding of a card inside it. See
+   docs/internal/model.md#modifiers. */
+@utility tight {
+  @layer families {
+    --_m-tight: ;
+  }
+}
+
+@utility loose {
+  @layer families {
+    --_m-loose: ;
+  }
+}
+
+@utility vertical {
+  @layer families {
+    --_m-vertical: ;
+  }
+}
+
+@utility horizontal {
+  @layer families {
+    --_m-horizontal: ;
+  }
+}
+
+@utility between {
+  @layer families {
+    --_m-between: ;
+  }
+}
+
+@utility narrow {
+  @layer families {
+    --_m-narrow: ;
+  }
+}
+
+@utility wide {
+  @layer families {
+    --_m-wide: ;
+  }
+}
+
+@utility p-xs {
+  @layer families {
+    --_m-p-xs: ;
+  }
+}
+
+@utility p-sm {
+  @layer families {
+    --_m-p-sm: ;
+  }
+}
+
+@utility p-lg {
+  @layer families {
+    --_m-p-lg: ;
+  }
+}
+
+@utility flush {
+  @layer families {
+    --_m-flush: ;
+  }
+}
+
+@utility icon {
+  @layer families {
+    --_m-icon: ;
+  }
+}
+
+@utility pill {
+  @layer families {
+    --_m-pill: ;
+  }
+}
+
+@utility active {
+  @layer families {
+    --_m-active: ;
+  }
+}
+
+@utility indeterminate {
+  @layer families {
+    --_m-indeterminate: ;
+  }
+}
+
+/* Rules between a table's body rows, and no lines at all. These two write the
+   public token directly, as `edged` writes `--ui-border`: `--ui-rule` already
+   cascades, so the class on a container rules every table inside it. */
+@utility ruled {
+  @layer families {
+    --ui-rule: 100%;
+  }
+}
+
+@utility ruleless {
+  @layer families {
+    --ui-rule: 0%;
+  }
+}