@sixthshift/design-system 0.2.1 → 0.4.0

package/src/components/Card/Card.tsx

@@ -8,6 +8,19 @@ export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
   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>` when `title` and/or `headerAction` is passed.
+ *
+ * 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, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
   const isInteractive = !!onClick;
 
@@ -24,9 +37,9 @@ export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, ti
     <div
       ref={ref}
       className={cn(
-        "rounded-xl border border-border-normal bg-bg-normal p-6 text-fg-normal shadow",
+        "card border-(color:--card-border) rounded-xl border bg-(--card-bg) p-6 text-(--card-fg) shadow",
         isInteractive &&
-          "cursor-pointer transition-colors hover:border-border-strong focus-visible:outline-2 focus-visible:outline-border-strong focus-visible:outline-offset-2",
+          "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",
         className
       )}
       onClick={onClick}

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",