@dashforge/tw 0.5.0-beta → 0.7.0-beta

package/src/components/Table/table.types.ts

@@ -0,0 +1,346 @@
+import type { ReactNode } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { TableVariants } from './table.variants.js';
+
+// ───── Nested key util ─────
+
+/**
+ * Type-level dotted path through an object's nested structure.
+ *
+ * `NestedKeyOf<{ user: { name: string } }>` → `'user' | 'user.name'`.
+ *
+ * Used as the `field` of a column to give autocomplete on nested
+ * paths. The runtime lookup happens via `getNestedValue` in
+ * `_internal/getNestedValue.ts` (split on `.` and walk).
+ */
+export type NestedKeyOf<T extends object> = {
+  [K in keyof T & (string | number)]: T[K] extends object | undefined
+    ? T[K] extends ReadonlyArray<unknown>
+      ? `${K}`
+      : NonNullable<T[K]> extends object
+        ? `${K}` | `${K}.${NestedKeyOf<NonNullable<T[K]>>}`
+        : `${K}`
+    : `${K}`;
+}[keyof T & (string | number)];
+
+// ───── Column types ─────
+
+/**
+ * Auto-detected primitive type for a column. Drives smart defaults:
+ *  - `number`  → align right + monospace (`tabular-nums`)
+ *  - `date`    → align left + monospace (consistent ISO width)
+ *  - `boolean` → align center
+ *  - `string`  → align left (default)
+ *  - `unknown` → fallback to left, no monospace
+ */
+export type TableColumnInferredType =
+  | 'number'
+  | 'date'
+  | 'boolean'
+  | 'string'
+  | 'unknown';
+
+/**
+ * Context passed to a custom `cellRenderer`. Mirrors what the consumer
+ * needs to render a cell: row, resolved value, position, selection
+ * state, expand state, and the resolved RBAC access state for THIS
+ * column.
+ */
+export interface TableCellContext<T> {
+  row: T;
+  value: unknown;
+  rowIndex: number;
+  isSelected: boolean;
+  isExpanded: boolean;
+  /** Resolved RBAC state for this column. `null` if no `access` set. */
+  access: { hidden: boolean; disabled: boolean; readonly: boolean } | null;
+}
+
+/**
+ * One column definition for `<Table>`.
+ *
+ * **i18n**: pass `t('users.name')` directly to `header` — `header`
+ * accepts `string` for the common case. Use the function form
+ * `header: () => <span>…</span>` only when you need richer JSX.
+ *
+ * **Smart defaults**: when `align` / `monospace` are omitted, the
+ * Table auto-detects the column type from the first non-null value
+ * across the visible rows and applies `right + tabular-nums` for
+ * numbers, `center` for booleans, etc. Explicit props always win.
+ */
+export interface TableColumn<T extends object> {
+  /**
+   * Dotted path to the value in each row. Supports nested keys
+   * (`'address.city.zipCode'`) thanks to `NestedKeyOf<T>` typing +
+   * runtime `getNestedValue()`.
+   */
+  field: NestedKeyOf<T> | (string & {});
+
+  /**
+   * Visible header. Pass a translation string directly:
+   * `header: t('users.name')`. Use the function form for richer
+   * JSX (e.g. header with an icon).
+   */
+  header: string | (() => ReactNode);
+
+  /** Pixel width (`px`). Mutually informative with `flex`. */
+  width?: number;
+  /** Flex grow factor (CSS `flex: <n> 1 0`). */
+  flex?: number;
+  /** Minimum pixel width (for resizable columns — deferred to v1-bis). */
+  minWidth?: number;
+
+  /**
+   * Horizontal alignment. Default is auto-detected from value type
+   * (number → right, boolean → center, otherwise left).
+   */
+  align?: 'left' | 'right' | 'center';
+
+  /**
+   * Opt-in to a monospace **font family** for this column. The
+   * library never auto-applies `font-mono` — it would override the
+   * consumer's theme `font-sans`. Set `true` explicitly only when
+   * the design calls for a typewriter font (e.g. raw hex IDs).
+   *
+   * The dashforgePreset does NOT own the `fontFamily` axis; the
+   * consumer configures the mono stack in their own
+   * `tailwind.config.ts` (`theme.extend.fontFamily.mono`).
+   */
+  monospace?: boolean;
+
+  /**
+   * Apply `font-variant-numeric: tabular-nums` so every digit
+   * occupies the same width — clean alignment for currency / metric
+   * columns. Does NOT change the font family. Auto-applied for
+   * `number` and `date` columns; pass `false` explicitly to opt out
+   * or `true` to force on a string column.
+   */
+  tabularNums?: boolean;
+
+  /**
+   * Make the column sortable. Pass `true` for default comparator
+   * (works for string/number/date/boolean) or a custom
+   * `(a, b) => number`.
+   */
+  sortable?: boolean | ((a: T, b: T) => number);
+
+  /**
+   * Include this column in the global search filter.
+   * @default false
+   */
+  searchable?: boolean;
+
+  /**
+   * Enable per-column quick filter (text-based in v1).
+   * @default false
+   */
+  filterable?: boolean;
+
+  /**
+   * Custom cell renderer. Receives the full row + the resolved
+   * (potentially nested) value, the row index, selection state,
+   * expansion state, and the RBAC access state.
+   */
+  cellRenderer?: (ctx: TableCellContext<T>) => ReactNode;
+
+  /**
+   * Per-column RBAC. `onUnauthorized: 'hide'` removes the column
+   * entirely from header AND every row cell (a11y-correct).
+   * `disable` / `readonly` are forwarded to `cellRenderer` via
+   * `ctx.access` — the renderer is expected to honor them.
+   */
+  access?: AccessRequirement;
+
+  /**
+   * Pin this column during horizontal scroll. `'left'` (DataGrid v1)
+   * uses CSS `position: sticky; left: 0`. `'right'` is reserved for
+   * v1-bis (CSS edge cases around last-column borders). Table
+   * (non-virtualized) ignores this prop today — only DataGrid honors
+   * it (Sprint 4.2).
+   */
+  sticky?: 'left' | 'right';
+
+  /** Reserved for v1-bis (column-visibility dialog). */
+  hideable?: boolean;
+  defaultHidden?: boolean;
+}
+
+// ───── State models ─────
+
+export type TableSortDirection = 'asc' | 'desc';
+
+export interface TableSortItem {
+  field: string;
+  direction: TableSortDirection;
+}
+
+/**
+ * Sort model. Single-column sort = array of length 1. Multi-column
+ * sort = array of N (typically up to 3). The order matters: first
+ * item is the primary sort key, subsequent items break ties.
+ */
+export type TableSortModel = TableSortItem[];
+
+export interface TableFilterItem {
+  field: string;
+  /** Text substring match. Future ops: `equals`, `in`, `gte`, `lte`, `between`. */
+  op: 'contains';
+  value: string;
+}
+
+export type TableFilterModel = TableFilterItem[];
+
+export type TableRowSelectionMode = 'none' | 'single' | 'multiple';
+
+// ───── i18n labels ─────
+
+/**
+ * Internal default strings used by the Table for accessibility
+ * announcements, density toggle, search placeholder, etc. Pass the
+ * subset you need to translate; the rest fall back to English.
+ *
+ * For column headers, empty state, bulk actions and row action
+ * labels — pass the translated value directly via the matching
+ * prop (`header`, `emptyState`, `bulkActions`, `rowActions`).
+ */
+export interface TableLabels {
+  searchPlaceholder?: string;
+  noData?: string;
+  loading?: string;
+  ariaSortNone?: string;
+  ariaSortAscending?: string;
+  ariaSortDescending?: string;
+  ariaSelectRow?: string;
+  ariaSelectAllRows?: string;
+  ariaExpandRow?: string;
+  ariaCollapseRow?: string;
+  /** "X selected" — `{count}` placeholder gets replaced. */
+  selectedCount?: string;
+  clearSelection?: string;
+  /** Per-column filter Popover. */
+  filterColumn?: string;
+  filterApply?: string;
+  filterClear?: string;
+  /** Density toggle. */
+  density?: string;
+  densityCompact?: string;
+  densityComfortable?: string;
+  densitySpacious?: string;
+}
+
+// ───── Slot props ─────
+
+export interface TableSlotProps {
+  root?: { className?: string };
+  toolbar?: { className?: string };
+  search?: { className?: string };
+  scroll?: { className?: string };
+  table?: { className?: string };
+  thead?: { className?: string };
+  tbody?: { className?: string };
+  headerRow?: { className?: string };
+  headerCell?: { className?: string };
+  row?: { className?: string };
+  cell?: { className?: string };
+  emptyState?: { className?: string };
+  loadingOverlay?: { className?: string };
+  selectionCell?: { className?: string };
+  expandToggleCell?: { className?: string };
+  expandedRow?: { className?: string };
+  rowActionsCell?: { className?: string };
+  bulkActionFooter?: { className?: string };
+}
+
+// ───── Expandable rows config ─────
+
+export interface TableExpandableConfig<T> {
+  render: (row: T) => ReactNode;
+  expandedRowIds?: string[];
+  onExpandChange?: (ids: string[]) => void;
+}
+
+// ───── Main props ─────
+
+/**
+ * Props for `<Table>`.
+ *
+ * Hybrid declarative-first architecture: by default every state piece
+ * (sort, filter, search, selection, expansion) is internal. Pass the
+ * matching controlled prop + change handler to lift state up.
+ *
+ * Smart defaults: column types are auto-detected on first render —
+ * number columns get right-align + tabular-nums, dates get monospace,
+ * booleans get center-align, etc. Override via explicit `align` /
+ * `monospace` per column.
+ *
+ * Visual style: Stripe-inspired clean lines by default
+ * (`variant="lines"`), row actions revealed on hover, sticky header,
+ * `comfortable` density. Switch via variant / density / size props.
+ *
+ * i18n: column `header` accepts plain strings (use `t('...')`
+ * directly). All internal label strings configurable via `labels`
+ * prop with English defaults.
+ */
+export interface TableProps<T extends object>
+  extends Pick<TableVariants, 'variant' | 'size' | 'density'> {
+  // ───── Data ─────
+  rows: T[];
+  cols: TableColumn<T>[];
+  /** Stable row id resolver. Default: positional index. */
+  getRowId?: (row: T, index: number) => string;
+
+  // ───── Sort ─────
+  sortModel?: TableSortModel;
+  onSortChange?: (model: TableSortModel) => void;
+  /** Default sort applied when uncontrolled. */
+  defaultSortModel?: TableSortModel;
+
+  // ───── Search ─────
+  enableSearch?: boolean;
+  searchQuery?: string;
+  onSearchQueryChange?: (q: string) => void;
+  searchPlaceholder?: string;
+  searchDebounceMs?: number;
+
+  // ───── Per-column filter ─────
+  filterModel?: TableFilterModel;
+  onFilterChange?: (model: TableFilterModel) => void;
+
+  // ───── Selection ─────
+  rowSelection?: TableRowSelectionMode;
+  selectedRowIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+  /** Sticky bulk action footer (visible only when selection > 0). */
+  bulkActions?: (selectedRows: T[]) => ReactNode;
+
+  // ───── Expandable rows ─────
+  expandable?: TableExpandableConfig<T>;
+
+  // ───── Row actions (revealed on hover) ─────
+  rowActions?: (row: T) => ReactNode;
+
+  // ───── States ─────
+  loading?: boolean;
+  /** Number of skeleton rows shown while `loading=true`. @default 5 */
+  loadingRowCount?: number;
+  emptyState?: ReactNode;
+
+  // ───── A11Y ─────
+  /** Sticky header. @default true */
+  stickyHeader?: boolean;
+  /** Optional caption for screen readers. */
+  caption?: ReactNode;
+  /** Renders the caption visually too (otherwise sr-only). @default false */
+  showCaption?: boolean;
+
+  // ───── RBAC ─────
+  /** Table-level RBAC. `hide` returns null; `disable` greys everything. */
+  access?: AccessRequirement;
+
+  // ───── i18n ─────
+  labels?: TableLabels;
+
+  // ───── Customization escape hatches ─────
+  sx?: string;
+  slotProps?: TableSlotProps;
+}

package/src/components/Table/table.variants.ts

@@ -0,0 +1,207 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<Table>` variant recipe.
+ *
+ * Slots:
+ *  - `root`              — outer wrapper
+ *  - `toolbar`           — search + filter chips row above table
+ *  - `search`            — search input
+ *  - `scroll`            — `<div class="overflow-auto">` wrapping the table
+ *  - `table`             — `<table>` element
+ *  - `thead`             — `<thead>` (sticky positioning here)
+ *  - `tbody`             — `<tbody>`
+ *  - `headerRow`         — `<tr>` inside `<thead>`
+ *  - `headerCell`        — `<th>` cell
+ *  - `headerCellButton`  — `<button>` inside sortable `<th>`
+ *  - `row`               — `<tr>` inside `<tbody>` (data row)
+ *  - `cell`              — `<td>` data cell
+ *  - `selectionCell`     — first `<td>` when selection mode active
+ *  - `expandToggleCell`  — second `<td>` when expandable active
+ *  - `expandedRow`       — full-width `<tr>` rendered after an expanded row
+ *  - `rowActionsCell`    — last `<td>` when `rowActions` provided
+ *  - `emptyState`        — placeholder when rows is empty
+ *  - `loadingOverlay`    — skeleton overlay when loading
+ *  - `bulkActionFooter`  — sticky footer with bulk actions
+ *
+ * Variant axes:
+ *  - `variant` — visual row-division style:
+ *      - `plain`    — minimal separators
+ *      - `lines`    — Stripe-style thin horizontal dividers (default)
+ *      - `striped`  — alternating row backgrounds (zebra)
+ *      - `bordered` — full cell borders
+ *      - `card`     — each row rendered as a separate surface card
+ *  - `size`    — `sm` / `md` (default) / `lg`
+ *  - `density` — `compact` (40px row) / `comfortable` (default 48px) / `spacious` (56px)
+ *
+ * Smart-default alignment (per column) is applied by the Table
+ * component code, NOT here — it depends on the runtime-detected
+ * value type, which the recipe doesn't see.
+ *
+ * **Dashforge identity rule** (memory: `feedback_dashforge_preset_is_identity`):
+ * This recipe uses NO `dark:` variants on the neutral palette. The
+ * `dashforgePreset()` CSS-variable swap auto-inverts neutral tokens
+ * (`bg-neutral-50` is light surface in light mode, dark surface in
+ * dark mode — same class, different physical color). Adding a
+ * `dark:` variant on neutral palette = DOUBLE inversion = breaks
+ * dark mode. The selected-row state uses the canonical LeftNav
+ * `itemActive` pattern (`bg-primary-100 text-primary-900 font-medium`),
+ * which works in both modes because the primary palette has no
+ * inversion (both `bg` and `text` resolve to the same physical
+ * colors regardless of mode → guaranteed contrast).
+ */
+export const tableVariants = tv({
+  slots: {
+    root: 'w-full',
+    toolbar: 'flex flex-wrap items-center gap-3 mb-3',
+    search: [
+      'inline-flex items-center gap-2',
+      'w-full max-w-sm rounded-md',
+      'border border-neutral-300',
+      // bg-neutral-50 auto-inverts via CSS var swap (light in light mode,
+      // dark in dark mode). Same semantic as TextField wrapper.
+      'bg-neutral-50',
+      'focus-within:ring-2 focus-within:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+    ],
+    scroll: 'relative w-full overflow-auto rounded-md',
+    table: 'w-full caption-bottom text-left',
+    // thead matches the page surface (auto-inverts). When sticky the
+    // header sits opaque against the scroll content beneath it.
+    thead: 'bg-neutral-50',
+    tbody: '',
+    headerRow: '',
+    headerCell: [
+      // Less prominent than the body — secondary-text intent
+      // (auto-inverts: dark grey in light mode, light grey in dark).
+      'text-neutral-700',
+      'font-semibold whitespace-nowrap select-none',
+      'border-b border-neutral-200',
+    ],
+    headerCellButton: [
+      'group inline-flex items-center gap-1 select-none',
+      // hover increases prominence (auto-inverts).
+      'hover:text-neutral-900',
+      'focus:outline-none focus-visible:underline',
+      'transition-colors motion-reduce:transition-none',
+    ],
+    row: [
+      'group/row transition-colors motion-reduce:transition-none',
+      // bg-neutral-100 = "elevated above surface" in both modes via
+      // auto-inversion. Slightly visible against the table bg.
+      'hover:bg-neutral-100',
+      // Canonical LeftNav `itemActive` pattern — primary palette
+      // doesn't invert, so dark-navy text on light-blue bg in BOTH
+      // modes. Guaranteed contrast.
+      'data-[selected=true]:bg-primary-100',
+      'data-[selected=true]:text-primary-900',
+      'data-[selected=true]:font-medium',
+    ],
+    cell: [
+      // Auto-inverts — dark text in light mode, light text in dark mode.
+      'text-neutral-900',
+      'border-b border-neutral-200',
+      'align-middle',
+    ],
+    selectionCell: 'w-10 text-center',
+    expandToggleCell: 'w-10 text-center',
+    // Expanded panel uses one tier of elevation above the page surface.
+    expandedRow: 'bg-neutral-100',
+    rowActionsCell: [
+      'w-12 text-right',
+      // Row actions hidden until row is hovered or focus-within
+      // (Pencil & Paper UX pattern: reveal-on-hover reduces visual density).
+      'opacity-0 group-hover/row:opacity-100 group-focus-within/row:opacity-100',
+      'transition-opacity motion-reduce:transition-none',
+    ],
+    emptyState: [
+      'py-12 text-center text-neutral-500',
+    ],
+    loadingOverlay: [
+      'pointer-events-none',
+    ],
+    bulkActionFooter: [
+      'sticky bottom-0 z-20',
+      'flex flex-wrap items-center justify-between gap-3',
+      'px-3 py-2 mt-0',
+      'border-t border-neutral-200',
+      // Surface-elevated bg + shadow ladder.
+      'bg-neutral-50 shadow-md',
+    ],
+  },
+  variants: {
+    variant: {
+      plain: {},
+      lines: {
+        // Default — Stripe-style 1px horizontal dividers (already
+        // applied via `border-b` on row + cell). No extra style here.
+      },
+      striped: {
+        // bg-neutral-100/60 = subtle elevation tier (auto-inverts).
+        row: 'odd:bg-neutral-100/60',
+      },
+      bordered: {
+        table: 'border border-neutral-200',
+        cell: 'border-r last:border-r-0 border-neutral-200',
+        headerCell: 'border-r last:border-r-0 border-neutral-200',
+      },
+      card: {
+        scroll: 'overflow-visible',
+        table: 'border-separate border-spacing-y-2',
+        row: [
+          'rounded-lg shadow-sm',
+          // Each row becomes an elevated card above the surface.
+          'bg-neutral-50',
+        ],
+        cell: 'border-b-0 first:rounded-l-lg last:rounded-r-lg',
+        headerCell: 'border-b-0',
+      },
+    },
+    size: {
+      sm: {
+        headerCell: 'text-xs',
+        cell: 'text-xs',
+        search: 'text-xs',
+      },
+      md: {
+        headerCell: 'text-sm',
+        cell: 'text-sm',
+        search: 'text-sm',
+      },
+      lg: {
+        headerCell: 'text-base',
+        cell: 'text-base',
+        search: 'text-base',
+      },
+    },
+    density: {
+      // Pencil & Paper UX research: 40px / 48px / 56px row height.
+      compact: {
+        headerCell: 'px-2 py-1',
+        cell: 'px-2 py-1',
+      },
+      comfortable: {
+        headerCell: 'px-3 py-2',
+        cell: 'px-3 py-2',
+      },
+      spacious: {
+        headerCell: 'px-4 py-3',
+        cell: 'px-4 py-3',
+      },
+    },
+    stickyHeader: {
+      true: {
+        thead: 'sticky top-0 z-10',
+      },
+      false: {},
+    },
+  },
+  defaultVariants: {
+    variant: 'lines',
+    size: 'md',
+    density: 'comfortable',
+    stickyHeader: true,
+  },
+});
+
+export type TableVariants = VariantProps<typeof tableVariants>;

package/src/components/Tabs/tabs.variants.ts

@@ -19,21 +19,32 @@ export const tabsVariants = tv({
   variants: {
     variant: {
       underline: {
-        list: 'border-b border-neutral-200 dark:border-neutral-800',
+        // Neutral palette auto-inverts via CSS-var swap.
+        list: 'border-b border-neutral-200',
         trigger: [
-          'px-3 py-2 border-b-2 border-transparent text-neutral-600 dark:text-neutral-400',
-          'hover:text-neutral-900 dark:hover:text-neutral-50',
+          'px-3 py-2 border-b-2 border-transparent text-neutral-600',
+          'hover:text-neutral-900',
+          // Primary palette does NOT auto-invert — `dark:` shift is
+          // an intentional tone refinement (kept).
           'data-[state=active]:border-primary-500 data-[state=active]:text-primary-700',
           'dark:data-[state=active]:text-primary-400',
         ],
       },
       pill: {
-        list: 'rounded-lg bg-neutral-100 dark:bg-neutral-800 p-1',
+        // Pill list bg uses the elevation tier — auto-inverts.
+        list: 'rounded-lg bg-neutral-100 p-1',
         trigger: [
-          'px-3 py-1.5 rounded-md text-neutral-600 dark:text-neutral-400',
-          'hover:text-neutral-900 dark:hover:text-neutral-50',
-          'data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-900',
-          'data-[state=active]:text-neutral-900 dark:data-[state=active]:text-neutral-50',
+          'px-3 py-1.5 rounded-md text-neutral-600',
+          'hover:text-neutral-900',
+          // Active pill is one tier above the list bg
+          // (`bg-neutral-100`-inverted = #171717 in dark).
+          // `bg-white` is hardcoded so a `dark:` is required —
+          // target `dark:bg-neutral-200` (= #262626 in dark) sits
+          // ONE TIER above the list bg, preserving the elevation
+          // semantic from light mode (where `bg-white` sits above
+          // `bg-neutral-100` = #f5f5f5).
+          'data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-200',
+          'data-[state=active]:text-neutral-900',
           'data-[state=active]:shadow-sm',
         ],
       },

package/src/components/Tooltip/tooltip.variants.ts

@@ -4,14 +4,24 @@ export const tooltipVariants = tv({
   slots: {
     content: [
       'z-50 max-w-xs rounded-md px-3 py-1.5 text-xs font-medium',
+      // Auto-invert via the dashforgePreset() CSS-var swap:
+      //  - Light mode: `bg-neutral-900` = #171717 (dark surface) +
+      //    `text-neutral-50` = #fafafa (light text) — DARK tooltip
+      //    on the light page (high contrast).
+      //  - Dark mode: `bg-neutral-900` flips to #f5f5f5 (light) +
+      //    `text-neutral-50` flips to #0a0a0a (dark text) — LIGHT
+      //    tooltip on the dark page (high contrast against page).
+      // Adding `dark:bg-neutral-50 dark:text-neutral-900` (the old
+      // pattern) would force the dark-mode tooltip back to a dark
+      // surface — invisible against the dark page.
       'bg-neutral-900 text-neutral-50',
-      'dark:bg-neutral-50 dark:text-neutral-900',
       'shadow-md',
       'data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95',
       'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
       'motion-reduce:transition-none motion-reduce:duration-0',
     ],
-    arrow: 'fill-neutral-900 dark:fill-neutral-50',
+    // Arrow tracks the content bg — auto-inverts the same way.
+    arrow: 'fill-neutral-900',
   },
 });
 

package/src/components/Typography/Typography.test.tsx

@@ -219,8 +219,10 @@ describe('<Typography>', () => {
       const { container } = render(<Typography color={color}>x</Typography>);
       const cls = container.firstElementChild?.className ?? '';
       if (color === 'muted') {
+        // Sprint 4.3 identity sweep: neutral palette auto-inverts via
+        // CSS-var swap — no `dark:` variant needed.
         expect(cls).toContain('text-neutral-600');
-        expect(cls).toContain('dark:text-neutral-400');
+        expect(cls).not.toContain('dark:text-neutral-');
       } else {
         expect(cls).toContain(`text-${color}-700`);
         expect(cls).toContain(`dark:text-${color}-400`);

package/src/components/Typography/typography.variants.ts

@@ -62,8 +62,12 @@ export const typographyVariants = tv({
       warning:   'text-warning-700 dark:text-warning-400',
       danger:    'text-danger-700 dark:text-danger-400',
       info:      'text-info-700 dark:text-info-400',
-      neutral:   'text-neutral-900 dark:text-neutral-100',
-      muted:     'text-neutral-600 dark:text-neutral-400',
+      // Neutral palette auto-inverts via the dashforgePreset() CSS-var
+      // swap — no `dark:` variants. `text-neutral-900` resolves to
+      // dark text in light mode and light text in dark mode; same
+      // applies to `text-neutral-600` (muted).
+      neutral:   'text-neutral-900',
+      muted:     'text-neutral-600',
     },
 
     /*