@sixthshift/design-system 0.3.0 → 0.5.0

package/src/components/Calendar/calendar.types.ts

@@ -124,6 +124,16 @@ type CalendarViewBaseProps = {
   /** First day of week (0 = Sunday, 1 = Monday) */
   weekStartsOn?: WeekStartsOn | undefined;
 
+  /**
+   * Move DOM focus into the day grid on mount.
+   *
+   * Off by default: a grid that grabs focus when it appears is wrong for a
+   * pointer user who clicked a trigger. `DatePicker` turns it on only when the
+   * popover was opened from the keyboard (`Alt+ArrowDown`), where the whole
+   * point of opening it was to navigate days.
+   */
+  autoFocusDay?: boolean | undefined;
+
   /** Show footer with Today/Cancel/Apply buttons */
   showFooter?: boolean | undefined;
   /** Show Today button (only if showFooter=true) */

package/src/components/Card/Card.tsx

@@ -1,14 +1,118 @@
 import { cn } from "@sixthshift/design-system/utils";
+import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
-export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
-  /** Optional header title - string or ReactNode */
-  title?: React.ReactNode;
-  /** Optional action element displayed on the right side of the header */
-  headerAction?: React.ReactNode;
-};
+/**
+ * Geometry only, plus the five `--card-*` component tokens.
+ *
+ * Every colour reads a `--card-*` token whose value is decided by
+ * src/theme/recipes/card.css. `size` stays here: it is pure geometry
+ * (padding, header gap, corner radius), not colour, so it has no reason to
+ * move — the same split Message.tsx documents.
+ *
+ * The ramp is a density axis, not a padding setting. `md` is the middle and
+ * the default at 16px, which is also where MUI's `CardContent` and
+ * Bootstrap's `.card-body` sit; two steps exist below it for surfaces that
+ * repeat dozens of times, and two above for surfaces that are the page.
+ *
+ *   xs  8px   dense data — table-row cards, compact tiles, many at once
+ *   sm  12px  list rows and secondary cards; a line or two of content
+ *   md  16px  a standalone content card. The one to reach for by default
+ *   lg  24px  primary or feature cards — a main panel, a form container
+ *   xl  32px  hero, empty-state and marketing surfaces
+ *
+ * Steps are 8 · 12 · 16 · 24 · 32, alternating x1.5 and x1.33; 20px is
+ * skipped deliberately as the value that breaks that rhythm.
+ *
+ * Radius scales with padding and never exceeds it — at `xs` a 12px corner
+ * against 8px of padding visibly crowds the content. The header gap flattens
+ * at both ends instead of tracking padding: it separates a title from an
+ * action control, so it has a usability floor and nothing to gain above 16px.
+ *
+ * Type is deliberately absent from the ramp. Message's `size` carries
+ * `text-xs` because Message knows what it holds; Card is a container for
+ * arbitrary children, `Heading` and `Body` included, so setting type here
+ * would fight the typography ramp at every call site. Containers set
+ * spacing; content components set type.
+ */
+export const cardVariants = cva(
+  // One literal, deliberately: `useSortedClasses --unsafe` strips the trailing
+  // space before a `+`, silently welding the last class of one fragment to the
+  // first of the next. A single string means the sorter has nothing to break.
+  "card border-(color:--card-border) border bg-(--card-bg) text-(--card-fg) shadow",
+  {
+    variants: {
+      size: {
+        xs: "rounded-md p-2",
+        sm: "rounded-lg p-3",
+        md: "rounded-xl p-4",
+        lg: "rounded-xl p-6",
+        xl: "rounded-2xl p-8",
+      },
+      interactive: {
+        true: "hover:border-(color:--card-border-hovered) focus-visible:outline-(color:--card-ring) cursor-pointer transition-colors focus-visible:outline-2 focus-visible:outline-offset-2",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      interactive: false,
+    },
+  }
+);
 
-export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
+/**
+ * Header geometry per size: the gap between title and action, and the space
+ * below it.
+ *
+ * A `<div>`, not a `<header>`. A `<header>` whose nearest sectioning ancestor
+ * is the body becomes a `banner` landmark, so two titled cards on one page
+ * produced two banners — axe's `landmark-no-duplicate-banner`. A card's header
+ * is not the page's banner, and the element bought nothing else here.
+ */
+const headerVariants = cva("flex items-start justify-between", {
+  variants: {
+    size: {
+      xs: "mb-2 gap-2",
+      sm: "mb-3 gap-2",
+      md: "mb-4 gap-3",
+      lg: "mb-4 gap-4",
+      xl: "mb-6 gap-4",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export type CardSize = NonNullable<VariantProps<typeof cardVariants>["size"]>;
+
+export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> &
+  Pick<VariantProps<typeof cardVariants>, "size"> & {
+    /** Optional header title - string or ReactNode */
+    title?: React.ReactNode;
+    /** Optional action element displayed on the right side of the header */
+    headerAction?: React.ReactNode;
+  };
+
+/**
+ * Bordered, elevated container — the "this contains data" building block
+ * (see docs/visual-hierarchy.md's Elevated tier). Renders a `<div>`, with an
+ * optional header row when `title` and/or `headerAction` is passed.
+ *
+ * `size` is a density axis covering padding, header spacing and corner
+ * radius; `md` (16px) is the default. See `cardVariants` above for what each
+ * step is for and why type is not part of it.
+ *
+ * Passing `onClick` turns the whole card into a button: it gets
+ * `role="button"`, `tabIndex={0}`, and both Enter and Space activate it, not
+ * just a pointer click. Omit `onClick` for a purely presentational card.
+ *
+ * Colour reads `--card-*` component tokens (src/theme/recipes/card.css) —
+ * the same seam Button and Badge use — so a consumer can re-point them
+ * without a release.
+ */
+export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, size, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
   const isInteractive = !!onClick;
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -23,22 +127,17 @@ export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, ti
     // biome-ignore lint/a11y/noStaticElementInteractions: role="button" + tabIndex are added dynamically when onClick is present
     <div
       ref={ref}
-      className={cn(
-        "rounded-xl border border-border-normal bg-bg-normal p-6 text-fg-normal shadow",
-        isInteractive &&
-          "cursor-pointer transition-colors hover:border-border-strong focus-visible:outline-2 focus-visible:outline-border-strong focus-visible:outline-offset-2",
-        className
-      )}
+      className={cn(cardVariants({ size, interactive: isInteractive }), className)}
       onClick={onClick}
       onKeyDown={handleKeyDown}
       {...(isInteractive && { role: "button", tabIndex: 0 })}
       {...props}
     >
       {(title || headerAction) && (
-        <header className="mb-4 flex items-start justify-between gap-4">
+        <div className={headerVariants({ size })}>
           {title && <div className="font-semibold">{title}</div>}
           {headerAction && <div className="shrink-0">{headerAction}</div>}
-        </header>
+        </div>
       )}
       {children}
     </div>

package/src/components/Card/index.ts

@@ -1 +1 @@
-export { Card, type CardProps } from "./Card";
+export { Card, type CardProps, type CardSize, cardVariants } from "./Card";

package/src/components/Checkbox/Checkbox.tsx

@@ -51,6 +51,27 @@ const IndeterminateIcon = () => (
   </svg>
 );
 
+/**
+ * A single boolean, or tri-state, toggle — a custom button with
+ * `role="checkbox"` rather than a native `<input type="checkbox">`, so it
+ * can be styled without fighting native checkbox rendering.
+ *
+ * Controlled or uncontrolled via the `checked`/`defaultChecked`/
+ * `onCheckedChange` triad (`useControllableState`). `checked` also accepts
+ * `"indeterminate"`, which sets `aria-checked="mixed"` and swaps in a dash
+ * icon instead of the check — for a "select all" checkbox whose children are
+ * only partially selected. Clicking an indeterminate checkbox always
+ * resolves it to `true`, never back to indeterminate.
+ *
+ * Only participates in native form submission when `name` is set: a hidden
+ * native `<input type="checkbox">` is rendered alongside the button and
+ * kept in sync, carrying `value` (default `"on"`). Without `name`, state
+ * lives only in React and nothing is submitted.
+ *
+ * Passing `label` wraps the button and a `<Label>` together and wires
+ * `htmlFor`/`id` between them; without it, you get just the button and must
+ * supply your own accessible name.
+ */
 const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
   (
     {
@@ -93,8 +114,7 @@ const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
           ref={ref}
           onClick={() => setChecked(!isChecked)}
           className={cn(
-            "peer h-4 w-4 shrink-0 cursor-pointer rounded-xs border border-border-brand shadow focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
-            (isChecked || isIndeterminate) && "bg-bg-brand text-fg-on-brand",
+            "checkbox peer border-(color:--checkbox-border) focus-visible:ring-(color:--checkbox-ring) h-4 w-4 shrink-0 cursor-pointer rounded-xs border bg-(--checkbox-bg) text-(--checkbox-fg) shadow focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
             className
           )}
           {...props}

package/src/components/CheckboxGroup/CheckboxGroup.tsx

@@ -36,6 +36,28 @@ export type CheckboxGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onC
   onBlur?: () => void;
 };
 
+/**
+ * A set of related checkboxes sharing one controlled/uncontrolled `string[]`
+ * selection, via the `value`/`defaultValue`/`onValueChange` triad
+ * (`useControllableState`).
+ *
+ * `variant="default"` (the default) renders one `Checkbox` per option, each
+ * with its own visible label, laid out in a column or row per
+ * `orientation`. `variant="button"` is a separate rendering path — not a
+ * re-skinned `Checkbox` — a row/column of plain buttons with
+ * `role="checkbox"` and no separate label; contiguous buttons touch and
+ * share borders (`appearance="segmented"`, the default) or sit apart with
+ * their own rounded corners (`appearance="separate"`).
+ *
+ * Form submission only happens when `name` is set. In the default variant
+ * that means each underlying `Checkbox` gets `name`, so one hidden native
+ * checkbox input is rendered per option; in the button variant the group
+ * itself renders one hidden `<input type="checkbox">` per *currently
+ * selected* value.
+ *
+ * Renders `role="group"`; focus leaving the whole group — not just moving
+ * between options — fires `onBlur`.
+ */
 const CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(
   (
     {

package/src/components/Code/Editor/Editor.tsx

@@ -5,7 +5,7 @@ import { useCallback, useRef } from "react";
 import { useTheme } from "../../../hooks/useTheme";
 import type { ValidationError } from "../ValidationStatus";
 import { createSemanticTokensProvider, workerExtensionUrl } from "./semanticTokenProvider";
-import { defineThemes, PA_THEME_DARK, PA_THEME_LIGHT } from "./themes";
+import { defineThemes, EDITOR_THEME_DARK, EDITOR_THEME_LIGHT } from "./themes";
 
 let semanticTokensRegistered = false;
 function registerSemanticTokenProviders(monaco: typeof import("monaco-editor")) {
@@ -51,7 +51,7 @@ export type EditorProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
  */
 export const Editor = ({ value, onChange, onValidate, readOnly = false, className, typeDefinitions, compilerOptions = {}, ...props }: EditorProps) => {
   const { resolvedTheme } = useTheme();
-  const monacoTheme = resolvedTheme === "dark" ? PA_THEME_DARK : PA_THEME_LIGHT;
+  const monacoTheme = resolvedTheme === "dark" ? EDITOR_THEME_DARK : EDITOR_THEME_LIGHT;
   const editorRef = useRef<editor.IStandaloneCodeEditor | null>(null);
 
   const handleEditorDidMount = useCallback(

package/src/components/Code/Editor/themes.ts

@@ -1,40 +1,58 @@
 import type { editor } from "monaco-editor";
 
-export const PA_THEME_LIGHT = "pa-light";
-export const PA_THEME_DARK = "pa-dark";
+export const EDITOR_THEME_LIGHT = "ds-light";
+export const EDITOR_THEME_DARK = "ds-dark";
 
+/**
+ * The token palettes are One Light and One Dark, with every colour raised to
+ * 4.5:1 against the worst background it can land on — which is the active line's
+ * highlight, not the editor background, since that is the darker (light theme)
+ * or lighter (dark theme) of the two.
+ *
+ * Stock One Light fails that on 21 of its 25 token colours: syntax highlighting
+ * is text as far as axe is concerned, so it carries the full 4.5:1 obligation
+ * rather than the 3:1 that non-text contrast gets. Hue and saturation are kept;
+ * only lightness moves, and only as far as it has to. The most visible
+ * consequence is that comments recede less than in stock One Light — #a0a1a7
+ * managed 2.30.
+ *
+ * `scripts/check-contrast.ts` covers the design system's own tokens; these are
+ * Monaco's, so they are checked by the editor stories' a11y run instead. A story
+ * with a play function is what exercises it: without one, axe runs before Monaco
+ * has painted and sees nothing to measure.
+ */
 const lightTheme: editor.IStandaloneThemeData = {
   base: "vs",
   inherit: true,
   rules: [
     // Monarch tokenizer rules
-    { token: "comment", foreground: "a0a1a7", fontStyle: "italic" },
+    { token: "comment", foreground: "6b6c73", fontStyle: "italic" },
     { token: "keyword", foreground: "a626a4" },
-    { token: "string", foreground: "50a14f" },
-    { token: "number", foreground: "986801" },
+    { token: "string", foreground: "3c7a3c" },
+    { token: "number", foreground: "906301" },
     { token: "delimiter", foreground: "383a42" },
     { token: "delimiter.bracket", foreground: "383a42" },
-    { token: "tag", foreground: "e45649" },
-    { token: "attribute.name", foreground: "986801" },
-    { token: "attribute.value", foreground: "50a14f" },
-    { token: "operator", foreground: "0184bc" },
-    { token: "identifier", foreground: "e45649" },
+    { token: "tag", foreground: "cf2d1f" },
+    { token: "attribute.name", foreground: "906301" },
+    { token: "attribute.value", foreground: "3c7a3c" },
+    { token: "operator", foreground: "0174a5" },
+    { token: "identifier", foreground: "cf2d1f" },
 
     // Semantic token rules (TypeScript language service)
-    { token: "variable", foreground: "e45649" },
-    { token: "variable.readonly", foreground: "986801" },
+    { token: "variable", foreground: "cf2d1f" },
+    { token: "variable.readonly", foreground: "906301" },
     { token: "parameter", foreground: "383a42" },
-    { token: "property", foreground: "e45649" },
-    { token: "property.readonly", foreground: "986801" },
-    { token: "function", foreground: "4078f2" },
-    { token: "method", foreground: "4078f2" },
-    { token: "type", foreground: "c18401" },
-    { token: "type.identifier", foreground: "c18401" },
-    { token: "class", foreground: "c18401" },
-    { token: "interface", foreground: "c18401" },
-    { token: "enum", foreground: "c18401" },
-    { token: "enumMember", foreground: "986801" },
-    { token: "namespace", foreground: "e45649" },
+    { token: "property", foreground: "cf2d1f" },
+    { token: "property.readonly", foreground: "906301" },
+    { token: "function", foreground: "2162f0" },
+    { token: "method", foreground: "2162f0" },
+    { token: "type", foreground: "916301" },
+    { token: "type.identifier", foreground: "916301" },
+    { token: "class", foreground: "916301" },
+    { token: "interface", foreground: "916301" },
+    { token: "enum", foreground: "916301" },
+    { token: "enumMember", foreground: "906301" },
+    { token: "namespace", foreground: "cf2d1f" },
   ],
   colors: {
     "editor.background": "#fafafa",
@@ -60,23 +78,23 @@ const darkTheme: editor.IStandaloneThemeData = {
   inherit: true,
   rules: [
     // Monarch tokenizer rules
-    { token: "comment", foreground: "5c6370", fontStyle: "italic" },
-    { token: "keyword", foreground: "c678dd" },
+    { token: "comment", foreground: "939aa6", fontStyle: "italic" },
+    { token: "keyword", foreground: "c97edf" },
     { token: "string", foreground: "98c379" },
     { token: "number", foreground: "d19a66" },
     { token: "delimiter", foreground: "abb2bf" },
     { token: "delimiter.bracket", foreground: "abb2bf" },
-    { token: "tag", foreground: "e06c75" },
+    { token: "tag", foreground: "e37b83" },
     { token: "attribute.name", foreground: "d19a66" },
     { token: "attribute.value", foreground: "98c379" },
     { token: "operator", foreground: "56b6c2" },
-    { token: "identifier", foreground: "e06c75" },
+    { token: "identifier", foreground: "e37b83" },
 
     // Semantic token rules (TypeScript language service)
-    { token: "variable", foreground: "e06c75" },
+    { token: "variable", foreground: "e37b83" },
     { token: "variable.readonly", foreground: "d19a66" },
     { token: "parameter", foreground: "abb2bf" },
-    { token: "property", foreground: "e06c75" },
+    { token: "property", foreground: "e37b83" },
     { token: "property.readonly", foreground: "d19a66" },
     { token: "function", foreground: "61afef" },
     { token: "method", foreground: "61afef" },
@@ -86,7 +104,7 @@ const darkTheme: editor.IStandaloneThemeData = {
     { token: "interface", foreground: "e5c07b" },
     { token: "enum", foreground: "e5c07b" },
     { token: "enumMember", foreground: "d19a66" },
-    { token: "namespace", foreground: "e06c75" },
+    { token: "namespace", foreground: "e37b83" },
   ],
   colors: {
     "editor.background": "#282c34",
@@ -107,6 +125,6 @@ const darkTheme: editor.IStandaloneThemeData = {
 };
 
 export function defineThemes(monaco: typeof import("monaco-editor")) {
-  monaco.editor.defineTheme(PA_THEME_LIGHT, lightTheme);
-  monaco.editor.defineTheme(PA_THEME_DARK, darkTheme);
+  monaco.editor.defineTheme(EDITOR_THEME_LIGHT, lightTheme);
+  monaco.editor.defineTheme(EDITOR_THEME_DARK, darkTheme);
 }

package/src/components/Code/ValidationStatus/ValidationStatus.tsx

@@ -1,7 +1,7 @@
-import { Message } from "@sixthshift/design-system/message";
+import { Message, type MessageIntentName } from "@sixthshift/design-system/message";
 import { cn } from "@sixthshift/design-system/utils";
 import { AlertCircle, AlertTriangle, CheckCircle, Info } from "lucide-react";
-import type { ComponentProps, HTMLAttributes } from "react";
+import type { HTMLAttributes } from "react";
 
 export type ValidationError = {
   line: number;
@@ -16,7 +16,10 @@ export type ValidationStatusProps = HTMLAttributes<HTMLDivElement> & {
   maxRows?: number;
 };
 
-type Intent = NonNullable<ComponentProps<typeof Message>["intent"]>;
+// The closed union, not `ComponentProps<typeof Message>["intent"]`: that is now
+// widened to admit any string so consumers can add intents in CSS, which would
+// silently let a typo through this map.
+type Intent = MessageIntentName;
 
 const SEVERITY_INTENT: Record<ValidationError["severity"], Intent> = {
   error: "danger",