css-is-awesome 1.1.0

package/scss/api.scss

@@ -0,0 +1,61 @@
+// ============================================================================
+// API - Authoring Barrel (zero-emit)
+// ============================================================================
+// Import this in a COMPONENT stylesheet to reach the whole mixin/function API
+// WITHOUT emitting any CSS. Nothing is printed until you actually call a mixin.
+//
+// This is the entry point for per-component styles (e.g. Card.module.scss):
+//
+//   @use 'css-is-awesome/api' as cia;
+//
+//   .card {
+//     background: cia.color(surface-default);
+//     padding: cia.space(4);
+//     border-radius: cia.radius(md);
+//     @include cia.card-base($shadow: 2);
+//   }
+//
+// It emits ZERO bytes and NO `:root` block, so it is safe inside a
+// `.module.scss` under Next.js CSS Modules "pure" mode.
+//
+// The GLOBAL tokens (`:root { --… }`) and animation keyframes are emitted ONCE
+// at your app root by a separate import — the CSS bundle (`css-is-awesome`) or
+// a theme stylesheet. Tokens + keyframes live at the root; each component only
+// pulls in the mixins here. `cia.animate(fade-in)` emits an `animation-name`
+// that references the globally-defined keyframe — the keyframe itself is NOT
+// re-emitted per component (that is why `animations-utilities` is deliberately
+// NOT forwarded here; see `_index.scss` for the kitchen-sink barrel).
+//
+// See also:
+//   - `css-is-awesome`         → the CSS bundle (emits tokens + base, use once)
+//   - `css-is-awesome/tokens`  → tokens-only CSS
+//   - `css-is-awesome/api`     → THIS file: mixins/functions, zero emit
+// ============================================================================
+
+@use './system' as s;
+@use './theme' as t;
+
+// Forward the full authoring API. Every entry below is zero-emit: mixins and
+// functions print nothing until called; token maps are compile-time only.
+@forward './system' as sys-*;
+@forward './theme' as theme-*;
+@forward './generator';
+@forward './mixins';            // No prefix - main API
+@forward './layout';            // Layout mixins (grid, wrap, page)
+@forward './icons' as icon-*;   // Icon mixins with prefix
+@forward './animations';        // animate() + animate-on() mixins (CSS-Modules-safe)
+@forward './components';        // Component mixins (btn, card, nav, etc.)
+
+// NOTE: './animations-utilities' (keyframes + .cia-anim-* classes + global
+// reduced-motion safety net) is intentionally NOT forwarded here — it emits
+// CSS and belongs in the global bundle, loaded once.
+
+// Re-export key maps for advanced usage (variable declarations — no CSS).
+$spacing: s.$spacing;
+$breakpoints: s.$breakpoints;
+$z-layers: s.$z-layers;
+$font-sizes: s.$font-sizes;
+$theme-brand: t.$theme-brand;
+$theme-light: t.$theme-light;
+$theme-dark: t.$theme-dark;
+$theme-radius: t.$theme-radius;

package/scss/components/_accordion.scss

@@ -0,0 +1,72 @@
+// ============================================================================
+// ACCORDION
+// ============================================================================
+// Native <details name="..."> mutual exclusion. Zero JavaScript.
+//
+// Usage (mixin — the primary API):
+//   .faq-item { @include accordion; }
+//
+// Usage (utility class, opt-in convenience):
+//   <details name="faq" class="cia-accordion">
+//     <summary>Question</summary>
+//     <div>Answer</div>
+//   </details>
+//
+// Multiple <details name="faq"> at the same DOM level auto-close siblings
+// when one opens. Native browser behavior; no JS, no script tag, no hydration.
+// Baseline since 2024 (Chrome 120, Firefox 130, Safari 17.6).
+//
+// A11y: <details>/<summary> is keyboard-accessible by default (Tab + Space).
+// focus-ring routed through m.focus-ring for consistency.
+// ============================================================================
+@use '../mixins' as m;
+
+@mixin accordion {
+  border: 1px solid m.color(border-default);
+  border-radius: m.radius(md);
+  background: m.color(surface-default);
+  overflow: hidden;
+
+  & + & { margin-block-start: m.space(2); }
+
+  > summary {
+    cursor: pointer;
+    padding: m.space(3) m.space(4);
+    font-weight: m.font-weight(medium);
+    color: m.color(text-primary);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: m.space(2);
+    list-style: none;
+    min-height: var(--touch-target-min, 24px);                /* WCAG 2.2 SC 2.5.8 */
+    @include m.transition(background-color);
+
+    &::-webkit-details-marker { display: none; }              /* Safari */
+
+    &::after {
+      content: '';
+      width: 0.55em;
+      height: 0.55em;
+      border-right: 2px solid currentColor;
+      border-bottom: 2px solid currentColor;
+      transform: rotate(45deg);
+      transition: transform var(--duration-fast, 180ms) var(--ease, ease);
+      flex-shrink: 0;
+    }
+
+    &:hover { background: m.color(interactive-hover); }
+
+    @include m.focus-ring;
+  }
+
+  &[open] > summary::after {
+    transform: rotate(-135deg);
+  }
+
+  > :not(summary) {
+    padding: m.space(3) m.space(4);
+    padding-block-start: 0;
+    color: m.color(text-secondary);
+  }
+}

package/scss/components/_buttons.scss

@@ -0,0 +1,171 @@
+// ============================================================================
+// BUTTONS
+// ============================================================================
+// Mixin-first button system. One router (`btn`) covers every variant.
+// Each variant is a small private mixin; the router stays small no matter
+// how many variants you add.
+//
+// Numeric scale keys are the source of truth (1..9). T-shirt keys still
+// work as aliases — both of the following produce identical output:
+//   .btn-small-numeric { @include btn-base($py: 1, $px: 2, $font-size: 2); }
+//   .btn-small-tshirt  { @include btn-base($py: xs, $px: sm, $font-size: sm); }
+//
+// Usage:
+//   .btn       { @include btn-base; }
+//   .btn-cta   { @include btn(primary, $px: 6, $r: full); }
+//   .btn-warn  { @include btn(warning); }
+//   .btn-edit  { @include btn(outline) { letter-spacing: 0.05em; } }
+//
+// To add a new variant: write a `_btn-<name>` private mixin below and add
+// one branch to the router. Status variants (info/success/warning/error)
+// are FREE — they share `_btn-status` via token interpolation.
+// ============================================================================
+@use 'sass:map';
+@use '../theme' as t;
+@use '../system' as s;
+@use '../mixins' as m;
+
+// ----------------------------------------------------------------------------
+// BASE — shared structural rules (display, padding, radius, focus-ring, …)
+// ----------------------------------------------------------------------------
+@mixin btn-base(
+  $py: 1,
+  $px: 4,
+  $r: md,
+  $font-weight: medium,
+  $font-size: null
+) {
+  @include m.button-reset;
+  display: inline-flex;
+  align-items: center;
+  gap: m.space(1);
+  min-height: var(--touch-target-min, 24px);                   /* WCAG 2.2 SC 2.5.8 */
+  font-weight: var(--btn-font-weight, #{m.font-weight($font-weight)});
+  padding: var(--btn-padding-y, #{m.space($py)}) var(--btn-padding-x, #{m.space($px)});
+  border-radius: var(--btn-radius, #{m.radius($r)});
+  @include m.transition(background-color, border-color, color, box-shadow);
+  @include m.focus-ring;
+
+  @if $font-size {
+    font-size: var(--btn-font-size, #{m.font-size($font-size)});
+  }
+}
+
+// ----------------------------------------------------------------------------
+// ROUTER — btn($variant)
+// ----------------------------------------------------------------------------
+// One mixin handles every variant. Defaults come from the theme contract;
+// every token is overridable via named args. `$args...` forwards to
+// btn-base for sizing (`$py`, `$px`, `$r`, `$font-weight`, `$font-size`).
+@mixin btn(
+  $variant,
+  $bg: null, $bg-hover: null, $bg-active: null,
+  $color: null, $border: null,
+  $args...
+) {
+  @include btn-base($args...);
+
+  @if      $variant == primary   { @include _btn-solid(action-primary-default,   action-primary-hover,   action-primary-active,   $bg, $bg-hover, $bg-active, $color); } @else if $variant == secondary { @include _btn-solid(action-secondary-default, action-secondary-hover, action-secondary-active, $bg, $bg-hover, $bg-active, $color); } @else if $variant == outline   { @include _btn-outline($color, $border); } @else if $variant == ghost     { @include _btn-ghost($color); } @else if $variant == info or
+           $variant == success or
+           $variant == warning or
+           $variant == error     { @include _btn-status($variant, $bg, $border, $color); } @else if $variant == disabled  { @include _btn-disabled($bg, $border); } @else if $variant == action    { @include _btn-status(info, $bg, $border, $color); }
+// back-compat alias for old buttonold
+  @else {
+    @error "btn(): unknown variant '#{$variant}'. Expected one of: primary, secondary, outline, ghost, info, success, warning, error, disabled, action.";
+  }
+
+  @content;
+}
+
+// ----------------------------------------------------------------------------
+// PER-VARIANT PRIVATE MIXINS — small, local, easy to grow.
+// ----------------------------------------------------------------------------
+
+// Solid variants — same shape, different default tokens. Used by primary,
+// secondary, and any future "filled" variant (e.g. tertiary).
+//
+// State cascade: when consumer passes only $bg (custom palette), hover +
+// active derive from $bg via the same color-mix(in oklch) formula m.states()
+// uses (12% hover, 20% active, light-dark-aware). Explicit $bg-hover /
+// $bg-active still take precedence when supplied. No $bg = original behavior
+// (use $hover / $active token defaults).
+@mixin _btn-solid(
+  $default, $hover, $active,
+  $bg: null, $bg-hover: null, $bg-active: null, $color: null
+) {
+  background: m.color($bg or $default);
+  color: m.color($color or text-inverse);
+
+  &:hover {
+    @if $bg-hover {
+      background: m.color($bg-hover);
+    } @else if $bg {
+      background: color-mix(in oklch, m.color($bg), light-dark(black, white) 12%);
+    } @else {
+      background: m.color($hover);
+    }
+  }
+
+  &:active {
+    @if $bg-active {
+      background: m.color($bg-active);
+    } @else if $bg {
+      background: color-mix(in oklch, m.color($bg), light-dark(black, white) 20%);
+    } @else {
+      background: m.color($active);
+    }
+  }
+
+  &:disabled, &[disabled] { @include m.disabled; }
+}
+
+// Outline variant — transparent bg, visible border, hover bg + border swap.
+@mixin _btn-outline($color: null, $border: null) {
+  background: transparent;
+  border: 1px solid m.color($border or border-default);
+  color: m.color($color or text-primary);
+  &:hover  {
+    background: m.color(interactive-hover);
+    border-color: m.color(border-focus);
+  }
+  &:active { background: m.color(interactive-active); }
+  &:disabled, &[disabled] { @include m.disabled; }
+}
+
+// Ghost variant — transparent bg, no border, hover bg only.
+@mixin _btn-ghost($color: null) {
+  background: transparent;
+  color: m.color($color or text-primary);
+  &:hover  { background: m.color(interactive-hover); }
+  &:active { background: m.color(interactive-active); }
+  &:disabled, &[disabled] { @include m.disabled; }
+}
+
+// Status variants — token interpolation. Adding a new status is FREE if the
+// tokens exist in the contract: <status>-subtle, <status>-default, <status>-text.
+@mixin _btn-status($status, $bg: null, $border: null, $color: null) {
+  background: m.color($bg or #{$status}-subtle);
+  border: 1px solid m.color($border or #{$status}-default);
+  color: m.color($color or #{$status}-text);
+}
+
+// Disabled state — looks disabled AND disables interaction.
+@mixin _btn-disabled($bg: null, $border: null) {
+  background: m.color($bg or surface-muted);
+  border: 1px solid m.color($border or border-default);
+  @include m.disabled;
+}
+
+// ----------------------------------------------------------------------------
+// ICON BUTTON — different shape (square, no padding system), kept separate.
+// ----------------------------------------------------------------------------
+@mixin btn-icon($size: 2.5rem, $r: md) {
+  @include m.button-reset;
+  @include m.flex($justify: center);
+  width: $size;
+  height: $size;
+  border-radius: m.radius($r);
+  @include m.transition(background-color, color);
+  @include m.focus-ring;
+  @include m.interactive;
+}

package/scss/components/_copy-button.scss

@@ -0,0 +1,69 @@
+// ============================================================================
+// COPY BUTTON
+// ============================================================================
+// Reusable copy-to-clipboard button. Decoupled from any parent context;
+// consumer wires it to any element via `data-copy-target="#id"`.
+//
+// Usage (mixin — primary API):
+//   .doc-copy { @include copy-button; }
+//
+// Usage (utility class):
+//   <pre id="snippet">…</pre>
+//   <button data-copy-target="#snippet" class="cia-copy-button">Copy</button>
+//
+// cia ships ZERO JavaScript in the npm package. Wire your own click handler
+// to read `data-copy-target` and call navigator.clipboard.writeText().
+//
+// Copy-paste recipe + the framework-free shim are documented at
+// /docs/recipes/copy-button on the cia site. A separate add-on package
+// (@cia/copy-button) is on the v1.x roadmap.
+//
+// Toast variant: pair the button with <div popover="hint" class="cia-copy-toast">
+// and add `popovertarget="..."` to the button. Native popover handles show;
+// your handler calls hidePopover() after a timeout for auto-hide.
+// ============================================================================
+@use '../mixins' as m;
+@use './overlay' as o;
+
+@mixin copy-button {
+  display: inline-flex;
+  align-items: center;
+  gap: m.space(1);
+  padding: m.space(1) m.space(2);
+  min-height: var(--touch-target-min, 24px);                  /* WCAG 2.2 SC 2.5.8 */
+  font-family: m.font-family(mono);
+  font-size: m.font-size(2);
+  line-height: 1.2;
+  letter-spacing: 0.04em;
+  color: m.color(text-secondary);
+  background: m.color(surface-raised);
+  border: 1px solid m.color(border-default);
+  border-radius: m.radius(sm);
+  cursor: pointer;
+  @include m.transition(background-color, color, border-color);
+  @include m.focus-ring;
+
+  &:hover {
+    background: m.color(surface-emphasis);
+    color: m.color(text-primary);
+    border-color: m.color(border-emphasis);
+  }
+
+  /* Copied state — JS shim toggles data-copied="true" for 1.5s */
+  &[data-copied='true'] {
+    background: m.color(success-subtle);
+    color: m.color(success-text);
+    border-color: m.color(success-default);
+  }
+}
+
+// Toast variant — composes with the tooltip mixin from overlay.
+// Used as a separate element triggered by the copy button via popovertarget.
+@mixin copy-toast {
+  @include o.tooltip;
+  background: m.color(success-default);
+  color: m.color(text-inverse);
+  font-family: m.font-family(primary);
+  font-size: m.font-size(2);
+  white-space: normal;
+}

package/scss/components/_data.scss

@@ -0,0 +1,190 @@
+// ============================================================================
+// DATA DISPLAY — Table, Card, List, Badge, Avatar
+// ============================================================================
+@use 'sass:map';
+@use '../theme' as t;
+@use '../system' as s;
+@use '../mixins' as m;
+
+// ----------------------------------------------------------------------------
+// BADGE — moved here from _feedback.scss in v0.8.1 (alongside card / table).
+// ----------------------------------------------------------------------------
+@mixin badge-base(
+  $py: 1,
+  $px: 1,
+  $r: full,
+  $font-size: 1
+) {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--badge-padding-y, #{m.space($py)}) var(--badge-padding-x, #{m.space($px)});
+  border-radius: var(--badge-radius, #{m.radius($r)});
+  @include m.font(medium, $font-size);
+}
+
+@mixin badge($status: info) {
+  @include badge-base;
+  background: m.color(#{$status}-subtle);
+  color: m.color(#{$status}-text);
+}
+
+// ----------------------------------------------------------------------------
+// TABLE
+// ----------------------------------------------------------------------------
+// Usage:
+//   table { @include table-base; }
+//   table { @include table-base($striped: true, $hover: true); }
+
+@mixin table-base($striped: false, $hover: false, $bordered: false, $compact: false) {
+  width: 100%;
+  border-collapse: collapse;
+  @include m.font(reg, 2);
+
+  th, td {
+    text-align: left;
+    padding: m.space(if(sass($compact): 1; else: 2)) m.space(if(sass($compact): 2; else: 4));
+    border-bottom: 1px solid m.color(border-default);
+  }
+
+  th {
+    @include m.font(semibold, 1);
+    color: m.color(text-secondary);
+    text-transform: uppercase;
+    letter-spacing: map.get(s.$letter-spacings, wide);
+  }
+
+  @if $bordered {
+    th, td { border: 1px solid m.color(border-default); }
+  }
+
+  @if $striped {
+    tbody tr:nth-child(even) {
+      background: m.color(surface-subtle);
+    }
+  }
+
+  @if $hover {
+    tbody tr {
+      @include m.transition(background-color);
+      &:hover { background: m.color(interactive-hover); }
+    }
+  }
+}
+
+// Responsive table wrapper
+@mixin table-responsive {
+  width: 100%;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+// ----------------------------------------------------------------------------
+// CARD
+// ----------------------------------------------------------------------------
+@mixin card-base(
+  $p: 4,
+  $r: lg,
+  $shadow: 1,
+  $bg: surface-default,
+  $border: false
+) {
+  padding: var(--card-padding, #{m.space($p)});
+  border-radius: var(--card-radius, #{m.radius($r)});
+  background: m.color($bg);
+
+  @if $shadow and $shadow != none {
+    box-shadow: var(--card-shadow, #{m.shadow($shadow)});
+  }
+
+  @if $border {
+    border: var(--card-border, 1px solid #{m.color(border-default)});
+  }
+}
+
+@mixin card-header($pb: 2) {
+  padding-block-end: m.space($pb);
+  border-block-end: 1px solid m.color(border-default);
+  margin-block-end: m.space(4);
+}
+
+@mixin card-footer($pt: 2) {
+  padding-block-start: m.space($pt);
+  border-block-start: 1px solid m.color(border-default);
+  margin-block-start: m.space(4);
+}
+
+@mixin card-interactive {
+  cursor: pointer;
+  @include m.transition(box-shadow, transform);
+
+  &:hover {
+    box-shadow: m.shadow(2);
+    transform: translateY(-1px);
+  }
+
+  &:active {
+    transform: translateY(0);
+  }
+}
+
+// ----------------------------------------------------------------------------
+// LIST
+// ----------------------------------------------------------------------------
+@mixin list-base($gap: 0, $dividers: false) {
+  @include m.list-reset;
+  display: flex;
+  flex-direction: column;
+  gap: m.space($gap);
+
+  @if $dividers and $gap == 0 {
+    > li + li { border-top: 1px solid m.color(border-default); }
+  }
+}
+
+// Usage:
+//   li { @include list-item; }
+//   li { @include list-item($interactive: true); }
+@mixin list-item($py: 2, $px: 4, $interactive: false) {
+  display: flex;
+  align-items: center;
+  gap: m.space(2);
+  padding: m.space($py) m.space($px);
+
+  @if $interactive {
+    cursor: pointer;
+    @include m.transition(background-color);
+    &:hover  { background: m.color(interactive-hover); }
+    &:active { background: m.color(interactive-active); }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// AVATAR
+// ----------------------------------------------------------------------------
+@mixin avatar($size: 2.5rem, $r: full) {
+  width: $size;
+  height: $size;
+  border-radius: m.radius($r);
+  object-fit: cover;
+  flex-shrink: 0;
+}
+
+@mixin avatar-placeholder($size: 2.5rem, $r: full, $bg: surface-muted, $color: text-muted) {
+  @include m.flex($justify: center);
+  width: $size;
+  height: $size;
+  border-radius: m.radius($r);
+  background: m.color($bg);
+  color: m.color($color);
+  @include m.font(semibold, 2);
+  flex-shrink: 0;
+}
+
+@mixin avatar-group($overlap: -0.5rem) {
+  display: flex;
+
+  > * + * {
+    margin-left: $overlap;
+    border: 2px solid m.color(surface-default);
+  }
+}