From 22d592b61e3dda7afd138c1643ee21bf9f8cb244 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:01:27 +0000
Subject: [PATCH 01/10] feat(input): add Input and Textarea form controls

Input and Textarea ship the label/helperText/error/size (sm/md) API with
native DOM onChange, matching the paper-ui call sites. The control id is
auto-generated with useId unless the caller passes one, and the label wires
to it via htmlFor. helperText and error share one line: error replaces
helperText and flips aria-invalid plus aria-describedby, and the inset
border re-tints to --fui-status-error-text.

size intentionally shadows the native input size attribute (numeric px),
hence InputProps Omit<>s it from InputHTMLAttributes.

The frosted inset-bordered look mirrors Card and secondary Button:
--fui-surface fill with backdrop blur that resolves to none inside Glass,
and a 2px inset in --fui-shadow-color that goes accent on focus.

Visual check of sm/md proportions is left to a human (headless run);
verification was check-types + lint + build only.
---
 papercamp/ideas/IDEA-2.md                    |  2 +-
 src/components/input/index.ts                |  2 +
 src/components/input/input.module.scss       | 74 +++++++++++++++++++
 src/components/input/input.tsx               | 44 ++++++++++++
 src/components/textarea/index.ts             |  2 +
 src/components/textarea/textarea.module.scss | 76 ++++++++++++++++++++
 src/components/textarea/textarea.tsx         | 44 ++++++++++++
 src/index.ts                                 |  6 ++
 8 files changed, 249 insertions(+), 1 deletion(-)
 create mode 100644 src/components/input/index.ts
 create mode 100644 src/components/input/input.module.scss
 create mode 100644 src/components/input/input.tsx
 create mode 100644 src/components/textarea/index.ts
 create mode 100644 src/components/textarea/textarea.module.scss
 create mode 100644 src/components/textarea/textarea.tsx

diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index db73e1c..133ad3a 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -14,7 +14,7 @@ The medium-usage band from the paper-camp inventory: Input (8 files), Modal (6),
 API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (native-like); Select takes an `options` array and value-based `onChange` (matching how all 7 call sites use it). Modal ships compound parts — `Modal.Body`, `Modal.Footer`, `Modal.Error` — because the identical body/footer/error-line scaffolding is copy-pasted across all six paper-camp modals today.
 
 ### Phases
-- [ ] Input + Textarea (label, helperText, error, sm/md)
+- [x] Input + Textarea (label, helperText, error, sm/md)
 - [ ] Select (options array, controlled value, keyboard nav, hidden native select for forms)
 - [ ] Checkbox + Switch
 - [ ] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
diff --git a/src/components/input/index.ts b/src/components/input/index.ts
new file mode 100644
index 0000000..188cbaa
--- /dev/null
+++ b/src/components/input/index.ts
@@ -0,0 +1,2 @@
+export { Input } from './input';
+export type { InputProps } from './input';
diff --git a/src/components/input/input.module.scss b/src/components/input/input.module.scss
new file mode 100644
index 0000000..2ccec9f
--- /dev/null
+++ b/src/components/input/input.module.scss
@@ -0,0 +1,74 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: $space-2;
+}
+
+.label {
+  font-family: $font-family-mono;
+  font-size: $font-size-sm;
+  font-weight: 700;
+  text-transform: lowercase;
+  letter-spacing: 0.02em;
+}
+
+.input {
+  width: 100%;
+  border: none;
+  background-color: var(--fui-surface);
+  color: var(--fui-text);
+  font-family: $font-family-sans;
+  line-height: 1.4;
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--fui-shadow-color);
+  backdrop-filter: var(--fui-nested-backdrop, blur(12px));
+  transition:
+    box-shadow 120ms ease,
+    background-color 200ms ease;
+
+  &::placeholder {
+    opacity: 0.5;
+  }
+
+  &:focus {
+    box-shadow: inset 0 0 0 2px var(--fui-accent);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.invalid {
+  box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+
+  &:focus {
+    box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+  }
+}
+
+// ─── Sizes ─────────────────────────────────────────────────────
+.md {
+  padding: $space-2 $space-3;
+  font-size: $font-size-md;
+}
+
+.sm {
+  padding: $space-1 $space-3;
+  font-size: $font-size-sm;
+}
+
+.message {
+  margin: 0;
+  font-size: $font-size-sm;
+  opacity: 0.7;
+}
+
+.error {
+  opacity: 1;
+  color: var(--fui-status-error-text);
+}
diff --git a/src/components/input/input.tsx b/src/components/input/input.tsx
new file mode 100644
index 0000000..cd736ef
--- /dev/null
+++ b/src/components/input/input.tsx
@@ -0,0 +1,44 @@
+import { type InputHTMLAttributes, forwardRef, useId } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './input.module.scss';
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  label?: string;
+  helperText?: string;
+  error?: string;
+  size?: 'sm' | 'md';
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  { label, helperText, error, size = 'md', id, className, ...props },
+  ref,
+) {
+  const uid = useId();
+  const inputId = id ?? `fui-input-${uid}`;
+  const messageId = `fui-input-message-${uid}`;
+  const invalid = error != null;
+  const message = invalid ? error : helperText;
+
+  return (
+    <div className={cn(styles.field, className)}>
+      {label && (
+        <label htmlFor={inputId} className={styles.label}>
+          {label}
+        </label>
+      )}
+      <input
+        ref={ref}
+        id={inputId}
+        className={cn(styles.input, styles[size], invalid && styles.invalid)}
+        aria-invalid={invalid || undefined}
+        aria-describedby={message != null ? messageId : undefined}
+        {...props}
+      />
+      {message != null && (
+        <p id={messageId} className={cn(styles.message, invalid && styles.error)}>
+          {message}
+        </p>
+      )}
+    </div>
+  );
+});
diff --git a/src/components/textarea/index.ts b/src/components/textarea/index.ts
new file mode 100644
index 0000000..9b0ac27
--- /dev/null
+++ b/src/components/textarea/index.ts
@@ -0,0 +1,2 @@
+export { Textarea } from './textarea';
+export type { TextareaProps } from './textarea';
diff --git a/src/components/textarea/textarea.module.scss b/src/components/textarea/textarea.module.scss
new file mode 100644
index 0000000..81af0ee
--- /dev/null
+++ b/src/components/textarea/textarea.module.scss
@@ -0,0 +1,76 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: $space-2;
+}
+
+.label {
+  font-family: $font-family-mono;
+  font-size: $font-size-sm;
+  font-weight: 700;
+  text-transform: lowercase;
+  letter-spacing: 0.02em;
+}
+
+.textarea {
+  width: 100%;
+  min-height: 6rem;
+  resize: vertical;
+  border: none;
+  background-color: var(--fui-surface);
+  color: var(--fui-text);
+  font-family: $font-family-sans;
+  line-height: 1.6;
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--fui-shadow-color);
+  backdrop-filter: var(--fui-nested-backdrop, blur(12px));
+  transition:
+    box-shadow 120ms ease,
+    background-color 200ms ease;
+
+  &::placeholder {
+    opacity: 0.5;
+  }
+
+  &:focus {
+    box-shadow: inset 0 0 0 2px var(--fui-accent);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.invalid {
+  box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+
+  &:focus {
+    box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+  }
+}
+
+// ─── Sizes ─────────────────────────────────────────────────────
+.md {
+  padding: $space-2 $space-3;
+  font-size: $font-size-md;
+}
+
+.sm {
+  padding: $space-1 $space-3;
+  font-size: $font-size-sm;
+}
+
+.message {
+  margin: 0;
+  font-size: $font-size-sm;
+  opacity: 0.7;
+}
+
+.error {
+  opacity: 1;
+  color: var(--fui-status-error-text);
+}
diff --git a/src/components/textarea/textarea.tsx b/src/components/textarea/textarea.tsx
new file mode 100644
index 0000000..a679daf
--- /dev/null
+++ b/src/components/textarea/textarea.tsx
@@ -0,0 +1,44 @@
+import { type TextareaHTMLAttributes, forwardRef, useId } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './textarea.module.scss';
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label?: string;
+  helperText?: string;
+  error?: string;
+  size?: 'sm' | 'md';
+}
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(
+  { label, helperText, error, size = 'md', id, className, ...props },
+  ref,
+) {
+  const uid = useId();
+  const inputId = id ?? `fui-textarea-${uid}`;
+  const messageId = `fui-textarea-message-${uid}`;
+  const invalid = error != null;
+  const message = invalid ? error : helperText;
+
+  return (
+    <div className={cn(styles.field, className)}>
+      {label && (
+        <label htmlFor={inputId} className={styles.label}>
+          {label}
+        </label>
+      )}
+      <textarea
+        ref={ref}
+        id={inputId}
+        className={cn(styles.textarea, styles[size], invalid && styles.invalid)}
+        aria-invalid={invalid || undefined}
+        aria-describedby={message != null ? messageId : undefined}
+        {...props}
+      />
+      {message != null && (
+        <p id={messageId} className={cn(styles.message, invalid && styles.error)}>
+          {message}
+        </p>
+      )}
+    </div>
+  );
+});
diff --git a/src/index.ts b/src/index.ts
index af1e717..67faa2a 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -36,4 +36,10 @@ export type {
 export { Card } from './components/card';
 export type { CardProps } from './components/card';
 
+export { Input } from './components/input';
+export type { InputProps } from './components/input';
+
+export { Textarea } from './components/textarea';
+export type { TextareaProps } from './components/textarea';
+
 export { cn } from './utils/style-helpers';

From 9b11544735b0236ea0d679377b1fead38a9e52cb Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:01:56 +0000
Subject: [PATCH 02/10] feat(release): Input + Textarea (label, helperText,
 error, sm/md)

Refs: IDEA-2
---
 package.json              | 11 ++---------
 papercamp/ideas/IDEA-4.md |  7 ++++---
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/package.json b/package.json
index 3a8dd57..e55295e 100644
--- a/package.json
+++ b/package.json
@@ -3,10 +3,7 @@
   "version": "0.1.1",
   "description": "Glossy, noisy, cosy React component library — frosted glass, film grain, and lava glow",
   "type": "module",
-  "sideEffects": [
-    "**/*.css",
-    "**/*.scss"
-  ],
+  "sideEffects": ["**/*.css", "**/*.scss"],
   "packageManager": "pnpm@10.12.1",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -96,10 +93,6 @@
     "vite-plugin-dts": "^4.5.4"
   },
   "pnpm": {
-    "onlyBuiltDependencies": [
-      "@biomejs/biome",
-      "@swc/core",
-      "esbuild"
-    ]
+    "onlyBuiltDependencies": ["@biomejs/biome", "@swc/core", "esbuild"]
   }
 }
diff --git a/papercamp/ideas/IDEA-4.md b/papercamp/ideas/IDEA-4.md
index db5158a..3fd1afb 100644
--- a/papercamp/ideas/IDEA-4.md
+++ b/papercamp/ideas/IDEA-4.md
@@ -13,8 +13,9 @@ Every component shipped in IDEA-1..3 needs an entry in the showcase's Components
 
 ### Phases
 - [x] Tier 1 entries: IconButton, Stamp, Tooltip, Toast (+ extend Button entry with danger/icons/isActive)
-
-### Log
-- 2026-08-04 — IconButton and Stamp entries live (with variant/size/dot controls, clickable-stamp counter demo); Button entry gained the danger option; Card entry shows sm/md sizes plus a keyboard-accessible clickable card. Tooltip/Toast entries pending their components.
 - [ ] Tier 2 entries: form controls, Modal, feedback components
 - [ ] Tier 3 entries: gap-fillers + icon-set grid
+
+### Log
+- 2026-08-04 — IconButton and Stamp entries live (with variant/size/dot controls, clickable-stamp counter demo); Button entry gained the danger option; Card entry shows sm/md sizes plus a keyboard-accessible clickable card. Tooltip/Toast entries now live too.
+- 2026-08-04 — Structure fix: an earlier Log insertion accidentally split the Phases list, orphaning the Tier 2/3 phases inside the Log — the idea parsed as one checked phase. Restored all three phases under Phases.

From 89706aed43e437e33b922167a690f22c59d5a20c Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:19:05 +0000
Subject: [PATCH 03/10] feat(release): Select (options array, controlled value,
 keyboard nav, hidden native select for forms)

Refs: IDEA-2
---
 biome.json                               |  14 +-
 papercamp/config.json                    |  22 +++
 papercamp/ideas/IDEA-2.md                |   2 +-
 src/components/select/index.ts           |   2 +
 src/components/select/select.module.scss | 156 +++++++++++++++
 src/components/select/select.tsx         | 229 +++++++++++++++++++++++
 src/index.ts                             |   3 +
 7 files changed, 426 insertions(+), 2 deletions(-)
 create mode 100644 src/components/select/index.ts
 create mode 100644 src/components/select/select.module.scss
 create mode 100644 src/components/select/select.tsx

diff --git a/biome.json b/biome.json
index 1ee12c6..1d3e129 100644
--- a/biome.json
+++ b/biome.json
@@ -40,5 +40,17 @@
     "formatter": {
       "trailingCommas": "none"
     }
-  }
+  },
+  "overrides": [
+    {
+      "include": ["src/components/select/**"],
+      "linter": {
+        "rules": {
+          "a11y": {
+            "useSemanticElements": "off"
+          }
+        }
+      }
+    }
+  ]
 }
diff --git a/papercamp/config.json b/papercamp/config.json
index ac5d256..9dc702d 100644
--- a/papercamp/config.json
+++ b/papercamp/config.json
@@ -4,5 +4,27 @@
   "initializedAt": "2026-08-04T14:52:35.357Z",
   "nextId": {
     "idea": 9
+  },
+  "defaultAgents": {
+    "phase": {
+      "agent": "claude-code",
+      "model": "opus",
+      "effort": "high"
+    },
+    "planDraft": {
+      "agent": "claude-code",
+      "model": "opus",
+      "effort": "high"
+    },
+    "ideaExtend": {
+      "agent": "claude-code",
+      "model": "opus",
+      "effort": "high"
+    },
+    "commitSuggest": {
+      "agent": "claude-code",
+      "model": "sonnet",
+      "effort": "low"
+    }
   }
 }
diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index 133ad3a..2122523 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -15,7 +15,7 @@ API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (n
 
 ### Phases
 - [x] Input + Textarea (label, helperText, error, sm/md)
-- [ ] Select (options array, controlled value, keyboard nav, hidden native select for forms)
+- [x] Select (options array, controlled value, keyboard nav, hidden native select for forms)
 - [ ] Checkbox + Switch
 - [ ] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
 - [ ] ListItem (active, icon, trailing action slot)
diff --git a/src/components/select/index.ts b/src/components/select/index.ts
new file mode 100644
index 0000000..977a279
--- /dev/null
+++ b/src/components/select/index.ts
@@ -0,0 +1,2 @@
+export { Select } from './select';
+export type { SelectOption, SelectProps } from './select';
diff --git a/src/components/select/select.module.scss b/src/components/select/select.module.scss
new file mode 100644
index 0000000..9fe1d9d
--- /dev/null
+++ b/src/components/select/select.module.scss
@@ -0,0 +1,156 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: $space-2;
+}
+
+.label {
+  font-family: $font-family-mono;
+  font-size: $font-size-sm;
+  font-weight: 700;
+  text-transform: lowercase;
+  letter-spacing: 0.02em;
+}
+
+.control {
+  position: relative;
+}
+
+.trigger {
+  display: flex;
+  align-items: center;
+  gap: $space-2;
+  width: 100%;
+  border: none;
+  background-color: var(--fui-surface);
+  color: var(--fui-text);
+  font-family: $font-family-sans;
+  line-height: 1.4;
+  text-align: left;
+  cursor: pointer;
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--fui-shadow-color);
+  backdrop-filter: var(--fui-nested-backdrop, blur(12px));
+  transition:
+    box-shadow 120ms ease,
+    background-color 200ms ease;
+
+  &:focus {
+    box-shadow: inset 0 0 0 2px var(--fui-accent);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.placeholder .value {
+  opacity: 0.5;
+}
+
+.value {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.arrow {
+  flex-shrink: 0;
+  width: 0;
+  height: 0;
+  border-right: 4px solid transparent;
+  border-left: 4px solid transparent;
+  border-top: 5px solid currentcolor;
+  opacity: 0.6;
+}
+
+.invalid {
+  box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+
+  &:focus {
+    box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+  }
+}
+
+.md {
+  padding: $space-2 $space-3;
+  font-size: $font-size-md;
+}
+
+.sm {
+  padding: $space-1 $space-3;
+  font-size: $font-size-sm;
+}
+
+.list {
+  position: absolute;
+  z-index: 20;
+  top: calc(100% + #{$space-1});
+  right: 0;
+  left: 0;
+  max-height: 16rem;
+  margin: 0;
+  padding: $space-1;
+  overflow-y: auto;
+  list-style: none;
+  background-color: var(--fui-surface);
+  box-shadow:
+    inset 0 0 0 2px var(--fui-shadow-color),
+    $glass-shadow;
+  backdrop-filter: blur(12px);
+}
+
+.option {
+  display: block;
+  width: 100%;
+  padding: $space-2 $space-3;
+  border: none;
+  background: none;
+  color: var(--fui-text);
+  font-family: $font-family-sans;
+  font-size: inherit;
+  text-align: left;
+  cursor: pointer;
+
+  &[aria-selected='true'] {
+    font-weight: 700;
+    color: var(--fui-accent);
+  }
+}
+
+.active {
+  background-color: var(--fui-status-neutral-fill);
+}
+
+.optionDisabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.native {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.message {
+  margin: 0;
+  font-size: $font-size-sm;
+  opacity: 0.7;
+}
+
+.error {
+  opacity: 1;
+  color: var(--fui-status-error-text);
+}
diff --git a/src/components/select/select.tsx b/src/components/select/select.tsx
new file mode 100644
index 0000000..0d2275f
--- /dev/null
+++ b/src/components/select/select.tsx
@@ -0,0 +1,229 @@
+import { type KeyboardEvent, forwardRef, useEffect, useId, useRef, useState } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './select.module.scss';
+
+export interface SelectOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface SelectProps {
+  options: SelectOption[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  label?: string;
+  helperText?: string;
+  error?: string;
+  size?: 'sm' | 'md';
+  placeholder?: string;
+  disabled?: boolean;
+  name?: string;
+  required?: boolean;
+  id?: string;
+  className?: string;
+}
+
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(
+  {
+    options,
+    value,
+    defaultValue,
+    onChange,
+    label,
+    helperText,
+    error,
+    size = 'md',
+    placeholder = 'Select…',
+    disabled = false,
+    name,
+    required,
+    id,
+    className,
+  },
+  ref,
+) {
+  const uid = useId();
+  const selectId = id ?? `fui-select-${uid}`;
+  const listId = `fui-select-list-${uid}`;
+  const messageId = `fui-select-message-${uid}`;
+  const optionId = (index: number) => `${selectId}-option-${index}`;
+
+  const isControlled = value !== undefined;
+  const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+  const currentValue = isControlled ? value : internalValue;
+
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  const invalid = error != null;
+  const message = invalid ? error : helperText;
+  const selectedIndex = options.findIndex((o) => o.value === currentValue);
+  const selectedOption = selectedIndex >= 0 ? options[selectedIndex] : undefined;
+
+  const firstEnabled = () => options.findIndex((o) => !o.disabled);
+  const lastEnabled = () => {
+    for (let i = options.length - 1; i >= 0; i--) if (!options[i].disabled) return i;
+    return -1;
+  };
+  const nextEnabled = (from: number) => {
+    for (let i = from + 1; i < options.length; i++) if (!options[i].disabled) return i;
+    return from;
+  };
+  const prevEnabled = (from: number) => {
+    for (let i = from - 1; i >= 0; i--) if (!options[i].disabled) return i;
+    return from;
+  };
+
+  useEffect(() => {
+    if (!open) return;
+    const onPointer = (e: PointerEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    };
+    window.addEventListener('pointerdown', onPointer);
+    return () => window.removeEventListener('pointerdown', onPointer);
+  }, [open]);
+
+  const openList = () => {
+    setActiveIndex(selectedIndex >= 0 ? selectedIndex : firstEnabled());
+    setOpen(true);
+  };
+
+  const commit = (next: string) => {
+    if (!isControlled) setInternalValue(next);
+    onChange?.(next);
+    setOpen(false);
+    triggerRef.current?.focus();
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        if (open) setActiveIndex((i) => nextEnabled(i));
+        else openList();
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        if (open) setActiveIndex((i) => prevEnabled(i));
+        else openList();
+        break;
+      case 'Home':
+        if (open) {
+          e.preventDefault();
+          setActiveIndex(firstEnabled());
+        }
+        break;
+      case 'End':
+        if (open) {
+          e.preventDefault();
+          setActiveIndex(lastEnabled());
+        }
+        break;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        if (open && activeIndex >= 0) commit(options[activeIndex].value);
+        else openList();
+        break;
+      case 'Escape':
+        if (open) {
+          e.preventDefault();
+          setOpen(false);
+        }
+        break;
+      case 'Tab':
+        if (open) setOpen(false);
+        break;
+    }
+  };
+
+  return (
+    <div ref={rootRef} className={cn(styles.field, className)}>
+      {label && (
+        <label htmlFor={selectId} className={styles.label}>
+          {label}
+        </label>
+      )}
+      <div className={styles.control}>
+        <button
+          ref={triggerRef}
+          type="button"
+          id={selectId}
+          role="combobox"
+          aria-haspopup="listbox"
+          aria-expanded={open}
+          aria-controls={listId}
+          aria-activedescendant={open && activeIndex >= 0 ? optionId(activeIndex) : undefined}
+          aria-invalid={invalid || undefined}
+          aria-describedby={message != null ? messageId : undefined}
+          disabled={disabled}
+          className={cn(
+            styles.trigger,
+            styles[size],
+            invalid && styles.invalid,
+            !selectedOption && styles.placeholder,
+          )}
+          onClick={() => (open ? setOpen(false) : openList())}
+          onKeyDown={onKeyDown}
+        >
+          <span className={styles.value}>
+            {selectedOption ? selectedOption.label : placeholder}
+          </span>
+          <span className={styles.arrow} aria-hidden="true" />
+        </button>
+        {open && (
+          <div id={listId} role="listbox" tabIndex={-1} className={styles.list}>
+            {options.map((option, index) => (
+              <button
+                key={option.value}
+                type="button"
+                id={optionId(index)}
+                role="option"
+                tabIndex={-1}
+                aria-selected={option.value === currentValue}
+                disabled={option.disabled}
+                className={cn(
+                  styles.option,
+                  index === activeIndex && styles.active,
+                  option.disabled && styles.optionDisabled,
+                )}
+                onPointerMove={() => !option.disabled && setActiveIndex(index)}
+                onClick={() => commit(option.value)}
+              >
+                {option.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+      <select
+        ref={ref}
+        name={name}
+        value={currentValue}
+        required={required}
+        disabled={disabled}
+        aria-hidden="true"
+        tabIndex={-1}
+        className={styles.native}
+        onChange={(e) => commit(e.target.value)}
+      >
+        {!selectedOption && <option value={currentValue} />}
+        {options.map((option) => (
+          <option key={option.value} value={option.value} disabled={option.disabled}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+      {message != null && (
+        <p id={messageId} className={cn(styles.message, invalid && styles.error)}>
+          {message}
+        </p>
+      )}
+    </div>
+  );
+});
diff --git a/src/index.ts b/src/index.ts
index 67faa2a..602339e 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -42,4 +42,7 @@ export type { InputProps } from './components/input';
 export { Textarea } from './components/textarea';
 export type { TextareaProps } from './components/textarea';
 
+export { Select } from './components/select';
+export type { SelectOption, SelectProps } from './components/select';
+
 export { cn } from './utils/style-helpers';

From 5b81aa4e3f6ada51d7f1a7e24c5ff6e3bb622029 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:24:53 +0000
Subject: [PATCH 04/10] feat(release): Checkbox + Switch

Refs: IDEA-2
---
 papercamp/ideas/IDEA-2.md                    |   2 +-
 src/components/checkbox/checkbox.module.scss | 117 +++++++++++++++++
 src/components/checkbox/checkbox.tsx         |  49 +++++++
 src/components/checkbox/index.ts             |   2 +
 src/components/switch/index.ts               |   2 +
 src/components/switch/switch.module.scss     | 130 +++++++++++++++++++
 src/components/switch/switch.tsx             |  50 +++++++
 src/index.ts                                 |   6 +
 8 files changed, 357 insertions(+), 1 deletion(-)
 create mode 100644 src/components/checkbox/checkbox.module.scss
 create mode 100644 src/components/checkbox/checkbox.tsx
 create mode 100644 src/components/checkbox/index.ts
 create mode 100644 src/components/switch/index.ts
 create mode 100644 src/components/switch/switch.module.scss
 create mode 100644 src/components/switch/switch.tsx

diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index 2122523..83898fa 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -16,7 +16,7 @@ API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (n
 ### Phases
 - [x] Input + Textarea (label, helperText, error, sm/md)
 - [x] Select (options array, controlled value, keyboard nav, hidden native select for forms)
-- [ ] Checkbox + Switch
+- [x] Checkbox + Switch
 - [ ] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
 - [ ] ListItem (active, icon, trailing action slot)
 - [ ] Alert (semantic variants, dismissible) + Divider (orientation, label)
diff --git a/src/components/checkbox/checkbox.module.scss b/src/components/checkbox/checkbox.module.scss
new file mode 100644
index 0000000..de776c7
--- /dev/null
+++ b/src/components/checkbox/checkbox.module.scss
@@ -0,0 +1,117 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: $space-2;
+}
+
+.control {
+  display: inline-flex;
+  align-items: center;
+  gap: $space-2;
+  font-family: $font-family-sans;
+  line-height: 1.4;
+  color: var(--fui-text);
+  cursor: pointer;
+}
+
+.disabled {
+  cursor: not-allowed;
+}
+
+.input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.box {
+  position: relative;
+  flex-shrink: 0;
+  background-color: var(--fui-surface);
+  box-shadow: inset 0 0 0 2px var(--fui-shadow-color);
+  backdrop-filter: var(--fui-nested-backdrop, blur(12px));
+  transition:
+    box-shadow 120ms ease,
+    background-color 200ms ease;
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    margin: auto;
+    border: solid var(--fui-bg);
+    border-width: 0 2px 2px 0;
+    opacity: 0;
+    transform: translateY(-8%) rotate(45deg);
+    transition: opacity 120ms ease;
+  }
+}
+
+.text {
+  user-select: none;
+}
+
+.input:focus-visible + .box {
+  box-shadow: inset 0 0 0 2px var(--fui-accent);
+}
+
+.input:checked + .box {
+  background-color: var(--fui-accent);
+  box-shadow: inset 0 0 0 2px var(--fui-accent);
+
+  &::after {
+    opacity: 1;
+  }
+}
+
+.input:disabled + .box {
+  opacity: 0.5;
+}
+
+.input:disabled ~ .text {
+  opacity: 0.5;
+}
+
+.invalid {
+  box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+}
+
+.md .box {
+  width: 1.25rem;
+  height: 1.25rem;
+
+  &::after {
+    width: 0.375rem;
+    height: 0.625rem;
+  }
+}
+
+.sm .box {
+  width: 1rem;
+  height: 1rem;
+
+  &::after {
+    width: 0.3rem;
+    height: 0.55rem;
+  }
+}
+
+.message {
+  margin: 0;
+  font-size: $font-size-sm;
+  opacity: 0.7;
+}
+
+.error {
+  opacity: 1;
+  color: var(--fui-status-error-text);
+}
diff --git a/src/components/checkbox/checkbox.tsx b/src/components/checkbox/checkbox.tsx
new file mode 100644
index 0000000..599d01c
--- /dev/null
+++ b/src/components/checkbox/checkbox.tsx
@@ -0,0 +1,49 @@
+import { type InputHTMLAttributes, forwardRef, useId } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './checkbox.module.scss';
+
+export interface CheckboxProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+  label?: string;
+  helperText?: string;
+  error?: string;
+  size?: 'sm' | 'md';
+}
+
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox(
+  { label, helperText, error, size = 'md', id, className, disabled, ...props },
+  ref,
+) {
+  const uid = useId();
+  const inputId = id ?? `fui-checkbox-${uid}`;
+  const messageId = `fui-checkbox-message-${uid}`;
+  const invalid = error != null;
+  const message = invalid ? error : helperText;
+
+  return (
+    <div className={cn(styles.field, className)}>
+      <label
+        htmlFor={inputId}
+        className={cn(styles.control, styles[size], disabled && styles.disabled)}
+      >
+        <input
+          ref={ref}
+          id={inputId}
+          type="checkbox"
+          className={styles.input}
+          disabled={disabled}
+          aria-invalid={invalid || undefined}
+          aria-describedby={message != null ? messageId : undefined}
+          {...props}
+        />
+        <span className={cn(styles.box, invalid && styles.invalid)} aria-hidden="true" />
+        {label && <span className={styles.text}>{label}</span>}
+      </label>
+      {message != null && (
+        <p id={messageId} className={cn(styles.message, invalid && styles.error)}>
+          {message}
+        </p>
+      )}
+    </div>
+  );
+});
diff --git a/src/components/checkbox/index.ts b/src/components/checkbox/index.ts
new file mode 100644
index 0000000..edcc3da
--- /dev/null
+++ b/src/components/checkbox/index.ts
@@ -0,0 +1,2 @@
+export { Checkbox } from './checkbox';
+export type { CheckboxProps } from './checkbox';
diff --git a/src/components/switch/index.ts b/src/components/switch/index.ts
new file mode 100644
index 0000000..657ebac
--- /dev/null
+++ b/src/components/switch/index.ts
@@ -0,0 +1,2 @@
+export { Switch } from './switch';
+export type { SwitchProps } from './switch';
diff --git a/src/components/switch/switch.module.scss b/src/components/switch/switch.module.scss
new file mode 100644
index 0000000..2118071
--- /dev/null
+++ b/src/components/switch/switch.module.scss
@@ -0,0 +1,130 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: $space-2;
+}
+
+.control {
+  display: inline-flex;
+  align-items: center;
+  gap: $space-2;
+  font-family: $font-family-sans;
+  line-height: 1.4;
+  color: var(--fui-text);
+  cursor: pointer;
+}
+
+.disabled {
+  cursor: not-allowed;
+}
+
+.input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.track {
+  position: relative;
+  flex-shrink: 0;
+  border-radius: 999px;
+  background-color: var(--fui-surface);
+  box-shadow: inset 0 0 0 2px var(--fui-shadow-color);
+  backdrop-filter: var(--fui-nested-backdrop, blur(12px));
+  transition:
+    box-shadow 120ms ease,
+    background-color 200ms ease;
+}
+
+.knob {
+  position: absolute;
+  top: 50%;
+  left: 2px;
+  border-radius: 999px;
+  background-color: var(--fui-text);
+  transform: translateY(-50%);
+  transition:
+    transform 160ms ease,
+    background-color 200ms ease;
+}
+
+.text {
+  user-select: none;
+}
+
+.input:focus-visible + .track {
+  box-shadow: inset 0 0 0 2px var(--fui-accent);
+}
+
+.input:checked + .track {
+  background-color: var(--fui-accent);
+  box-shadow: inset 0 0 0 2px var(--fui-accent);
+
+  .knob {
+    background-color: var(--fui-bg);
+  }
+}
+
+.input:disabled + .track {
+  opacity: 0.5;
+}
+
+.input:disabled ~ .text {
+  opacity: 0.5;
+}
+
+.invalid {
+  box-shadow: inset 0 0 0 2px var(--fui-status-error-text);
+}
+
+.md {
+  .track {
+    width: 2.5rem;
+    height: 1.5rem;
+  }
+
+  .knob {
+    width: 1.125rem;
+    height: 1.125rem;
+  }
+
+  .input:checked + .track .knob {
+    transform: translateY(-50%) translateX(1rem);
+  }
+}
+
+.sm {
+  .track {
+    width: 2rem;
+    height: 1.25rem;
+  }
+
+  .knob {
+    width: 0.875rem;
+    height: 0.875rem;
+  }
+
+  .input:checked + .track .knob {
+    transform: translateY(-50%) translateX(0.75rem);
+  }
+}
+
+.message {
+  margin: 0;
+  font-size: $font-size-sm;
+  opacity: 0.7;
+}
+
+.error {
+  opacity: 1;
+  color: var(--fui-status-error-text);
+}
diff --git a/src/components/switch/switch.tsx b/src/components/switch/switch.tsx
new file mode 100644
index 0000000..6fb3518
--- /dev/null
+++ b/src/components/switch/switch.tsx
@@ -0,0 +1,50 @@
+import { type InputHTMLAttributes, forwardRef, useId } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './switch.module.scss';
+
+export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+  label?: string;
+  helperText?: string;
+  error?: string;
+  size?: 'sm' | 'md';
+}
+
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
+  { label, helperText, error, size = 'md', id, className, disabled, ...props },
+  ref,
+) {
+  const uid = useId();
+  const inputId = id ?? `fui-switch-${uid}`;
+  const messageId = `fui-switch-message-${uid}`;
+  const invalid = error != null;
+  const message = invalid ? error : helperText;
+
+  return (
+    <div className={cn(styles.field, className)}>
+      <label
+        htmlFor={inputId}
+        className={cn(styles.control, styles[size], disabled && styles.disabled)}
+      >
+        <input
+          ref={ref}
+          id={inputId}
+          type="checkbox"
+          className={styles.input}
+          disabled={disabled}
+          aria-invalid={invalid || undefined}
+          aria-describedby={message != null ? messageId : undefined}
+          {...props}
+        />
+        <span className={cn(styles.track, invalid && styles.invalid)} aria-hidden="true">
+          <span className={styles.knob} />
+        </span>
+        {label && <span className={styles.text}>{label}</span>}
+      </label>
+      {message != null && (
+        <p id={messageId} className={cn(styles.message, invalid && styles.error)}>
+          {message}
+        </p>
+      )}
+    </div>
+  );
+});
diff --git a/src/index.ts b/src/index.ts
index 602339e..e020be6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -45,4 +45,10 @@ export type { TextareaProps } from './components/textarea';
 export { Select } from './components/select';
 export type { SelectOption, SelectProps } from './components/select';
 
+export { Checkbox } from './components/checkbox';
+export type { CheckboxProps } from './components/checkbox';
+
+export { Switch } from './components/switch';
+export type { SwitchProps } from './components/switch';
+
 export { cn } from './utils/style-helpers';

From e3cc2b440113a428c615a75884d69e40825fe213 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:30:51 +0000
Subject: [PATCH 05/10] feat(release): Modal (open/onClose/title/size, focus
 trap, scroll lock, Escape) with Body/Footer/Error compound parts

Refs: IDEA-2
---
 biome.json                             |   2 +-
 papercamp/ideas/IDEA-2.md              |   2 +-
 src/components/modal/index.ts          |   2 +
 src/components/modal/modal.module.scss | 106 +++++++++++++++++++++
 src/components/modal/modal.tsx         | 127 +++++++++++++++++++++++++
 src/index.ts                           |   3 +
 6 files changed, 240 insertions(+), 2 deletions(-)
 create mode 100644 src/components/modal/index.ts
 create mode 100644 src/components/modal/modal.module.scss
 create mode 100644 src/components/modal/modal.tsx

diff --git a/biome.json b/biome.json
index 1d3e129..4f723fc 100644
--- a/biome.json
+++ b/biome.json
@@ -43,7 +43,7 @@
   },
   "overrides": [
     {
-      "include": ["src/components/select/**"],
+      "include": ["src/components/select/**", "src/components/modal/**"],
       "linter": {
         "rules": {
           "a11y": {
diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index 83898fa..1b9e3aa 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -17,7 +17,7 @@ API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (n
 - [x] Input + Textarea (label, helperText, error, sm/md)
 - [x] Select (options array, controlled value, keyboard nav, hidden native select for forms)
 - [x] Checkbox + Switch
-- [ ] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
+- [x] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
 - [ ] ListItem (active, icon, trailing action slot)
 - [ ] Alert (semantic variants, dismissible) + Divider (orientation, label)
 - [ ] Spinner + Progress + Skeleton
diff --git a/src/components/modal/index.ts b/src/components/modal/index.ts
new file mode 100644
index 0000000..1d7cc05
--- /dev/null
+++ b/src/components/modal/index.ts
@@ -0,0 +1,2 @@
+export { Modal } from './modal';
+export type { ModalProps } from './modal';
diff --git a/src/components/modal/modal.module.scss b/src/components/modal/modal.module.scss
new file mode 100644
index 0000000..6f65c25
--- /dev/null
+++ b/src/components/modal/modal.module.scss
@@ -0,0 +1,106 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: $space-4;
+}
+
+.backdrop {
+  position: absolute;
+  inset: 0;
+  border: none;
+  background-color: rgba(0, 0, 0, 0.6);
+  cursor: pointer;
+}
+
+.panel {
+  @include glass;
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  gap: $space-4;
+  width: 100%;
+  max-height: calc(100vh - #{$space-8});
+  padding: $space-5;
+  box-shadow:
+    inset 0 0 0 2px var(--fui-shadow-color),
+    $glass-shadow;
+  outline: none;
+}
+
+.sm {
+  max-width: 24rem;
+}
+
+.md {
+  max-width: 32rem;
+}
+
+.lg {
+  max-width: 48rem;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: $space-3;
+}
+
+.title {
+  margin: 0;
+  font-family: $font-family-title;
+  font-size: $font-size-xl;
+  font-weight: 700;
+}
+
+.close {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: $space-6;
+  height: $space-6;
+  border: none;
+  background: none;
+  color: var(--fui-text);
+  font-size: $font-size-xl;
+  line-height: 1;
+  cursor: pointer;
+  opacity: 0.6;
+  transition: opacity 120ms ease;
+
+  &:hover {
+    opacity: 1;
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: $space-4;
+  overflow-y: auto;
+}
+
+.footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: $space-2;
+}
+
+.errorText {
+  margin: 0;
+  font-size: $font-size-sm;
+  color: var(--fui-status-error-text);
+}
diff --git a/src/components/modal/modal.tsx b/src/components/modal/modal.tsx
new file mode 100644
index 0000000..c5fbc29
--- /dev/null
+++ b/src/components/modal/modal.tsx
@@ -0,0 +1,127 @@
+import { type ReactNode, useEffect, useId, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { cn } from '../../utils/style-helpers';
+import styles from './modal.module.scss';
+
+const focusableSelector =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  title?: string;
+  size?: 'sm' | 'md' | 'lg';
+  children: ReactNode;
+  className?: string;
+}
+
+interface ModalSlotProps {
+  children: ReactNode;
+  className?: string;
+}
+
+function ModalRoot({ open, onClose, title, size = 'md', children, className }: ModalProps) {
+  const uid = useId();
+  const titleId = `fui-modal-title-${uid}`;
+  const panelRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  useEffect(() => {
+    if (!open) return;
+    previouslyFocused.current = document.activeElement as HTMLElement | null;
+    panelRef.current?.focus();
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        onCloseRef.current();
+        return;
+      }
+      if (event.key !== 'Tab') return;
+      const focusables = panelRef.current?.querySelectorAll<HTMLElement>(focusableSelector);
+      if (!focusables || focusables.length === 0) {
+        event.preventDefault();
+        panelRef.current?.focus();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener('keydown', onKeyDown);
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      document.body.style.overflow = previousOverflow;
+      previouslyFocused.current?.focus();
+    };
+  }, [open]);
+
+  if (!open || typeof document === 'undefined') return null;
+
+  return createPortal(
+    <div className={styles.overlay}>
+      <button
+        type="button"
+        className={styles.backdrop}
+        aria-label="Close modal"
+        onClick={onClose}
+      />
+      <div
+        ref={panelRef}
+        className={cn(styles.panel, styles[size], className)}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? titleId : undefined}
+        tabIndex={-1}
+      >
+        <div className={styles.header}>
+          {title && (
+            <h2 id={titleId} className={styles.title}>
+              {title}
+            </h2>
+          )}
+          <button type="button" className={styles.close} aria-label="Close modal" onClick={onClose}>
+            ×
+          </button>
+        </div>
+        {children}
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+function ModalBody({ children, className }: ModalSlotProps) {
+  return <div className={cn(styles.body, className)}>{children}</div>;
+}
+
+function ModalFooter({ children, className }: ModalSlotProps) {
+  return <div className={cn(styles.footer, className)}>{children}</div>;
+}
+
+function ModalError({ children, className }: ModalSlotProps) {
+  if (!children) return null;
+  return (
+    <p role="alert" className={cn(styles.errorText, className)}>
+      {children}
+    </p>
+  );
+}
+
+export const Modal = Object.assign(ModalRoot, {
+  Body: ModalBody,
+  Footer: ModalFooter,
+  Error: ModalError,
+});
diff --git a/src/index.ts b/src/index.ts
index e020be6..c2767eb 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -51,4 +51,7 @@ export type { CheckboxProps } from './components/checkbox';
 export { Switch } from './components/switch';
 export type { SwitchProps } from './components/switch';
 
+export { Modal } from './components/modal';
+export type { ModalProps } from './components/modal';
+
 export { cn } from './utils/style-helpers';

From 7d4c20f396e0c8a23b708c6b2cb70f0658a87129 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:33:28 +0000
Subject: [PATCH 06/10] feat(release): ListItem (active, icon, trailing action
 slot)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clickable list row built on a native <button>: leading icon slot,
ellipsis-truncated content, and a trailing action slot for badges or
secondary controls. `active` renders the accent left-bar + tint used by
sidebar/nav call sites and sets aria-current. sm/md sizing matches the
other Tier 2 controls; size names use the film-ui sm/md convention rather
than paper-ui's `small` string.

Visual check left to a human — this run is headless with no browser.
Verified with check-types, biome, and stylelint.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 papercamp/ideas/IDEA-2.md                     |  2 +-
 src/components/list-item/index.ts             |  2 +
 .../list-item/list-item.module.scss           | 70 +++++++++++++++++++
 src/components/list-item/list-item.tsx        | 29 ++++++++
 src/index.ts                                  |  3 +
 5 files changed, 105 insertions(+), 1 deletion(-)
 create mode 100644 src/components/list-item/index.ts
 create mode 100644 src/components/list-item/list-item.module.scss
 create mode 100644 src/components/list-item/list-item.tsx

diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index 1b9e3aa..3bd7ea2 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -18,6 +18,6 @@ API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (n
 - [x] Select (options array, controlled value, keyboard nav, hidden native select for forms)
 - [x] Checkbox + Switch
 - [x] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
-- [ ] ListItem (active, icon, trailing action slot)
+- [x] ListItem (active, icon, trailing action slot)
 - [ ] Alert (semantic variants, dismissible) + Divider (orientation, label)
 - [ ] Spinner + Progress + Skeleton
diff --git a/src/components/list-item/index.ts b/src/components/list-item/index.ts
new file mode 100644
index 0000000..0466ceb
--- /dev/null
+++ b/src/components/list-item/index.ts
@@ -0,0 +1,2 @@
+export { ListItem } from './list-item';
+export type { ListItemProps } from './list-item';
diff --git a/src/components/list-item/list-item.module.scss b/src/components/list-item/list-item.module.scss
new file mode 100644
index 0000000..5b789e4
--- /dev/null
+++ b/src/components/list-item/list-item.module.scss
@@ -0,0 +1,70 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: $space-2;
+  width: 100%;
+  border: none;
+  background: none;
+  color: var(--fui-text);
+  font-family: $font-family-sans;
+  line-height: 1.4;
+  text-align: left;
+  cursor: pointer;
+  outline: none;
+  transition:
+    box-shadow 120ms ease,
+    background-color 200ms ease;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-status-neutral-fill);
+  }
+
+  &:focus-visible {
+    box-shadow: inset 0 0 0 2px var(--fui-accent);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.active {
+  background-color: var(--fui-status-neutral-fill);
+  box-shadow: inset 3px 0 0 0 var(--fui-accent);
+  color: var(--fui-accent);
+  font-weight: 700;
+}
+
+.icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+}
+
+.content {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.action {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+}
+
+.md {
+  padding: $space-2 $space-3;
+  font-size: $font-size-md;
+}
+
+.sm {
+  padding: $space-1 $space-3;
+  font-size: $font-size-sm;
+}
diff --git a/src/components/list-item/list-item.tsx b/src/components/list-item/list-item.tsx
new file mode 100644
index 0000000..16d959b
--- /dev/null
+++ b/src/components/list-item/list-item.tsx
@@ -0,0 +1,29 @@
+import { type ButtonHTMLAttributes, type ReactNode, forwardRef } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './list-item.module.scss';
+
+export interface ListItemProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  size?: 'sm' | 'md';
+  active?: boolean;
+  icon?: ReactNode;
+  action?: ReactNode;
+}
+
+export const ListItem = forwardRef<HTMLButtonElement, ListItemProps>(function ListItem(
+  { size = 'md', active = false, icon, action, className, children, ...props },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      aria-current={active || undefined}
+      className={cn(styles.item, styles[size], active && styles.active, className)}
+      {...props}
+    >
+      {icon && <span className={styles.icon}>{icon}</span>}
+      <span className={styles.content}>{children}</span>
+      {action && <span className={styles.action}>{action}</span>}
+    </button>
+  );
+});
diff --git a/src/index.ts b/src/index.ts
index c2767eb..05337d5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -54,4 +54,7 @@ export type { SwitchProps } from './components/switch';
 export { Modal } from './components/modal';
 export type { ModalProps } from './components/modal';
 
+export { ListItem } from './components/list-item';
+export type { ListItemProps } from './components/list-item';
+
 export { cn } from './utils/style-helpers';

From a483c55ee87b758e1ee54324c75497054c4b27c2 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 17:42:45 +0000
Subject: [PATCH 07/10] feat(release): Alert (semantic variants, dismissible) +
 Divider (orientation, label)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Alert: info/success/warning/error variants over the --fui-status tokens,
each with a variant icon and status-colored left accent bar; dismissible
adds a close button wired to onDismiss. role="alert" for error/warning,
role="status" otherwise. Spreads HTMLAttributes<HTMLDivElement>.

Divider: horizontal/vertical orientations render a semantic <hr>; a
horizontal label renders a flex wrapper with <hr> lines flanking the
label (keeps biome's useSemanticElements/useFocusableInteractive happy
without role hacks). Line color via color-mix on --fui-text.

Verification: check-types, biome, stylelint, and build all green. Visual
review in a browser is left to a human — this was done headless with no
display.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 papercamp/ideas/IDEA-2.md                  |  2 +-
 src/components/alert/alert.module.scss     | 89 ++++++++++++++++++++++
 src/components/alert/alert.tsx             | 60 +++++++++++++++
 src/components/alert/index.ts              |  2 +
 src/components/divider/divider.module.scss | 46 +++++++++++
 src/components/divider/divider.tsx         | 28 +++++++
 src/components/divider/index.ts            |  2 +
 src/index.ts                               |  6 ++
 8 files changed, 234 insertions(+), 1 deletion(-)
 create mode 100644 src/components/alert/alert.module.scss
 create mode 100644 src/components/alert/alert.tsx
 create mode 100644 src/components/alert/index.ts
 create mode 100644 src/components/divider/divider.module.scss
 create mode 100644 src/components/divider/divider.tsx
 create mode 100644 src/components/divider/index.ts

diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index 3bd7ea2..68d9d77 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -19,5 +19,5 @@ API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (n
 - [x] Checkbox + Switch
 - [x] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
 - [x] ListItem (active, icon, trailing action slot)
-- [ ] Alert (semantic variants, dismissible) + Divider (orientation, label)
+- [x] Alert (semantic variants, dismissible) + Divider (orientation, label)
 - [ ] Spinner + Progress + Skeleton
diff --git a/src/components/alert/alert.module.scss b/src/components/alert/alert.module.scss
new file mode 100644
index 0000000..2b869b5
--- /dev/null
+++ b/src/components/alert/alert.module.scss
@@ -0,0 +1,89 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: $space-2;
+  padding: $space-3;
+  background-color: var(--fui-status-neutral-fill);
+  color: var(--fui-text);
+  font-family: $font-family-sans;
+  font-size: $font-size-sm;
+  line-height: 1.4;
+  border-left: 4px solid var(--fui-status-neutral-text);
+}
+
+.icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  margin-top: 0.1em;
+}
+
+.message {
+  flex: 1;
+  min-width: 0;
+}
+
+.dismiss {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  margin: -0.25rem -0.25rem -0.25rem 0;
+  border: none;
+  padding: 0;
+  background: transparent;
+  color: inherit;
+  font-size: 1.125rem;
+  line-height: 1;
+  cursor: pointer;
+  opacity: 0.55;
+
+  &:hover {
+    opacity: 1;
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.info {
+  background-color: var(--fui-status-info-fill);
+  border-left-color: var(--fui-status-info-text);
+
+  .icon {
+    color: var(--fui-status-info-text);
+  }
+}
+
+.success {
+  background-color: var(--fui-status-success-fill);
+  border-left-color: var(--fui-status-success-text);
+
+  .icon {
+    color: var(--fui-status-success-text);
+  }
+}
+
+.warning {
+  background-color: var(--fui-status-warning-fill);
+  border-left-color: var(--fui-status-warning-text);
+
+  .icon {
+    color: var(--fui-status-warning-text);
+  }
+}
+
+.error {
+  background-color: var(--fui-status-error-fill);
+  border-left-color: var(--fui-status-error-text);
+
+  .icon {
+    color: var(--fui-status-error-text);
+  }
+}
diff --git a/src/components/alert/alert.tsx b/src/components/alert/alert.tsx
new file mode 100644
index 0000000..1cc0d85
--- /dev/null
+++ b/src/components/alert/alert.tsx
@@ -0,0 +1,60 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './alert.module.scss';
+
+export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
+
+export interface AlertProps extends HTMLAttributes<HTMLDivElement> {
+  variant?: AlertVariant;
+  dismissible?: boolean;
+  onDismiss?: () => void;
+  children: ReactNode;
+}
+
+const icons: Record<AlertVariant, ReactNode> = {
+  info: (
+    <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true">
+      <path d="M8 0a8 8 0 100 16A8 8 0 008 0zm1 12H7V7h2v5zM8 5.5A1.25 1.25 0 118 3a1.25 1.25 0 010 2.5z" />
+    </svg>
+  ),
+  success: (
+    <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true">
+      <path d="M8 0a8 8 0 100 16A8 8 0 008 0zm3.7 5.7l-4.4 4.4a1 1 0 01-1.4 0L3.7 8.3l1.4-1.4L6.6 8.4l3.7-3.7 1.4 1z" />
+    </svg>
+  ),
+  warning: (
+    <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true">
+      <path d="M7.1 1.5a1 1 0 011.8 0l6.4 12A1 1 0 0114.4 15H1.6a1 1 0 01-.9-1.5l6.4-12zM7 6v4h2V6H7zm0 5v2h2v-2H7z" />
+    </svg>
+  ),
+  error: (
+    <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true">
+      <path d="M8 0a8 8 0 100 16A8 8 0 008 0zm3 10.6L9.4 12 8 10.6 6.6 12 5 10.6 6.6 9 5 7.4 6.6 6 8 7.4 9.4 6 11 7.4 9.4 9 11 10.6z" />
+    </svg>
+  ),
+};
+
+export function Alert({
+  variant = 'info',
+  dismissible = false,
+  onDismiss,
+  className,
+  children,
+  ...props
+}: AlertProps) {
+  return (
+    <div
+      role={variant === 'error' || variant === 'warning' ? 'alert' : 'status'}
+      className={cn(styles.alert, styles[variant], className)}
+      {...props}
+    >
+      <span className={styles.icon}>{icons[variant]}</span>
+      <div className={styles.message}>{children}</div>
+      {dismissible && (
+        <button type="button" aria-label="Dismiss" className={styles.dismiss} onClick={onDismiss}>
+          ×
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/alert/index.ts b/src/components/alert/index.ts
new file mode 100644
index 0000000..fa1cc01
--- /dev/null
+++ b/src/components/alert/index.ts
@@ -0,0 +1,2 @@
+export { Alert } from './alert';
+export type { AlertProps, AlertVariant } from './alert';
diff --git a/src/components/divider/divider.module.scss b/src/components/divider/divider.module.scss
new file mode 100644
index 0000000..bbc3515
--- /dev/null
+++ b/src/components/divider/divider.module.scss
@@ -0,0 +1,46 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+$divider-line: color-mix(in srgb, var(--fui-text) 15%, transparent);
+
+.divider {
+  box-sizing: border-box;
+  margin: 0;
+  border: none;
+}
+
+.horizontal {
+  width: 100%;
+  height: 1px;
+  background-color: $divider-line;
+}
+
+.vertical {
+  align-self: stretch;
+  width: 1px;
+  min-height: 1em;
+  background-color: $divider-line;
+}
+
+.labelled {
+  display: flex;
+  align-items: center;
+  gap: $space-3;
+}
+
+.line {
+  flex: 1;
+  height: 1px;
+  margin: 0;
+  border: none;
+  background-color: $divider-line;
+}
+
+.label {
+  flex-shrink: 0;
+  color: var(--fui-status-neutral-text);
+  font-family: $font-family-sans;
+  font-size: $font-size-sm;
+  line-height: 1.2;
+  white-space: nowrap;
+}
diff --git a/src/components/divider/divider.tsx b/src/components/divider/divider.tsx
new file mode 100644
index 0000000..6e7ac5a
--- /dev/null
+++ b/src/components/divider/divider.tsx
@@ -0,0 +1,28 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './divider.module.scss';
+
+export interface DividerProps extends HTMLAttributes<HTMLElement> {
+  orientation?: 'horizontal' | 'vertical';
+  label?: ReactNode;
+}
+
+export function Divider({ orientation = 'horizontal', label, className, ...props }: DividerProps) {
+  if (orientation === 'horizontal' && label != null) {
+    return (
+      <div className={cn(styles.divider, styles.labelled, className)} {...props}>
+        <hr className={styles.line} />
+        <span className={styles.label}>{label}</span>
+        <hr className={styles.line} />
+      </div>
+    );
+  }
+
+  return (
+    <hr
+      aria-orientation={orientation}
+      className={cn(styles.divider, styles[orientation], className)}
+      {...props}
+    />
+  );
+}
diff --git a/src/components/divider/index.ts b/src/components/divider/index.ts
new file mode 100644
index 0000000..a2e4d4a
--- /dev/null
+++ b/src/components/divider/index.ts
@@ -0,0 +1,2 @@
+export { Divider } from './divider';
+export type { DividerProps } from './divider';
diff --git a/src/index.ts b/src/index.ts
index 05337d5..f1c7c2f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -57,4 +57,10 @@ export type { ModalProps } from './components/modal';
 export { ListItem } from './components/list-item';
 export type { ListItemProps } from './components/list-item';
 
+export { Alert } from './components/alert';
+export type { AlertProps, AlertVariant } from './components/alert';
+
+export { Divider } from './components/divider';
+export type { DividerProps } from './components/divider';
+
 export { cn } from './utils/style-helpers';

From 1c8cd31e5b911fdb15508e7955643b17dfaaa776 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 18:30:08 +0000
Subject: [PATCH 08/10] feat(release): Spinner + Progress + Skeleton
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spinner: sm/md/lg ring that spins via a linear keyframe over --fui-accent
on a color-mixed --fui-text track; renders a semantic <output> (implicit
role="status") with an aria-label so it announces without a role hack.
Reduced-motion slows the spin to a crawl rather than freezing it.

Progress: native <progress> for free progressbar semantics (no ARIA, no
focusable-interactive lint). value/max clamped; fill color overridable via
a --fui-progress-fill custom property piped to the ::-webkit/-moz value
pseudo-elements, height via inline style. Square film edges, no radius.

Skeleton: text/rect/circle variants, width/height props, glossy shimmer
sweep over a faint --fui-text tint; shimmer disabled under reduced-motion.

All export from the barrel. Verification: check-types, biome, stylelint,
and build all green. Visual review in a browser is left to a human — this
was done headless with no display.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 papercamp/ideas/IDEA-2.md                    |  4 +-
 src/components/progress/index.ts             |  2 +
 src/components/progress/progress.module.scss | 30 ++++++++++++
 src/components/progress/progress.tsx         | 33 +++++++++++++
 src/components/skeleton/index.ts             |  2 +
 src/components/skeleton/skeleton.module.scss | 49 ++++++++++++++++++++
 src/components/skeleton/skeleton.tsx         | 27 +++++++++++
 src/components/spinner/index.ts              |  2 +
 src/components/spinner/spinner.module.scss   | 44 ++++++++++++++++++
 src/components/spinner/spinner.tsx           | 16 +++++++
 src/index.ts                                 |  9 ++++
 11 files changed, 216 insertions(+), 2 deletions(-)
 create mode 100644 src/components/progress/index.ts
 create mode 100644 src/components/progress/progress.module.scss
 create mode 100644 src/components/progress/progress.tsx
 create mode 100644 src/components/skeleton/index.ts
 create mode 100644 src/components/skeleton/skeleton.module.scss
 create mode 100644 src/components/skeleton/skeleton.tsx
 create mode 100644 src/components/spinner/index.ts
 create mode 100644 src/components/spinner/spinner.module.scss
 create mode 100644 src/components/spinner/spinner.tsx

diff --git a/papercamp/ideas/IDEA-2.md b/papercamp/ideas/IDEA-2.md
index 68d9d77..a90df5d 100644
--- a/papercamp/ideas/IDEA-2.md
+++ b/papercamp/ideas/IDEA-2.md
@@ -2,7 +2,7 @@
 id: IDEA-2
 title: Tier 2 — form controls and overlays
 type: feat
-status: planned
+status: review
 created: 2026-08-04
 tags:
   - components
@@ -20,4 +20,4 @@ API conventions from observed usage: Input/Textarea keep DOM-event `onChange` (n
 - [x] Modal (open/onClose/title/size, focus trap, scroll lock, Escape) with Body/Footer/Error compound parts
 - [x] ListItem (active, icon, trailing action slot)
 - [x] Alert (semantic variants, dismissible) + Divider (orientation, label)
-- [ ] Spinner + Progress + Skeleton
+- [x] Spinner + Progress + Skeleton
diff --git a/src/components/progress/index.ts b/src/components/progress/index.ts
new file mode 100644
index 0000000..c5ccce4
--- /dev/null
+++ b/src/components/progress/index.ts
@@ -0,0 +1,2 @@
+export { Progress } from './progress';
+export type { ProgressProps } from './progress';
diff --git a/src/components/progress/progress.module.scss b/src/components/progress/progress.module.scss
new file mode 100644
index 0000000..b565301
--- /dev/null
+++ b/src/components/progress/progress.module.scss
@@ -0,0 +1,30 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.progress {
+  appearance: none;
+  display: block;
+  width: 100%;
+  border: none;
+  background-color: color-mix(in srgb, var(--fui-text) 12%, transparent);
+  color: var(--fui-progress-fill, var(--fui-accent));
+
+  &::-webkit-progress-bar {
+    background-color: transparent;
+  }
+
+  &::-webkit-progress-value {
+    background-color: var(--fui-progress-fill, var(--fui-accent));
+    transition: width 240ms ease;
+  }
+
+  &::-moz-progress-bar {
+    background-color: var(--fui-progress-fill, var(--fui-accent));
+  }
+
+  @include reduced-motion {
+    &::-webkit-progress-value {
+      transition: none;
+    }
+  }
+}
diff --git a/src/components/progress/progress.tsx b/src/components/progress/progress.tsx
new file mode 100644
index 0000000..08c5337
--- /dev/null
+++ b/src/components/progress/progress.tsx
@@ -0,0 +1,33 @@
+import type { CSSProperties, ProgressHTMLAttributes } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './progress.module.scss';
+
+export interface ProgressProps extends Omit<ProgressHTMLAttributes<HTMLProgressElement>, 'color'> {
+  value: number;
+  max?: number;
+  color?: string;
+  height?: number;
+}
+
+export function Progress({
+  value,
+  max = 100,
+  color,
+  height = 8,
+  className,
+  style,
+  ...props
+}: ProgressProps) {
+  const clamped = max > 0 ? Math.max(0, Math.min(value, max)) : 0;
+  const fill = color ? { '--fui-progress-fill': color } : undefined;
+
+  return (
+    <progress
+      value={clamped}
+      max={max}
+      className={cn(styles.progress, className)}
+      style={{ height, ...fill, ...style } as CSSProperties}
+      {...props}
+    />
+  );
+}
diff --git a/src/components/skeleton/index.ts b/src/components/skeleton/index.ts
new file mode 100644
index 0000000..9b1844a
--- /dev/null
+++ b/src/components/skeleton/index.ts
@@ -0,0 +1,2 @@
+export { Skeleton } from './skeleton';
+export type { SkeletonProps } from './skeleton';
diff --git a/src/components/skeleton/skeleton.module.scss b/src/components/skeleton/skeleton.module.scss
new file mode 100644
index 0000000..0c2e7f9
--- /dev/null
+++ b/src/components/skeleton/skeleton.module.scss
@@ -0,0 +1,49 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.skeleton {
+  position: relative;
+  display: inline-block;
+  overflow: hidden;
+  background-color: color-mix(in srgb, var(--fui-text) 9%, transparent);
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(
+      90deg,
+      transparent,
+      color-mix(in srgb, var(--fui-text) 8%, transparent),
+      transparent
+    );
+    transform: translateX(-100%);
+    animation: fui-skeleton-shimmer 1.4s ease-in-out infinite;
+  }
+
+  @include reduced-motion {
+    &::after {
+      animation: none;
+    }
+  }
+}
+
+.text {
+  width: 100%;
+  height: 0.8em;
+}
+
+.rect {
+  width: 100%;
+  height: 100%;
+}
+
+.circle {
+  border-radius: 999px;
+}
+
+@keyframes fui-skeleton-shimmer {
+  to {
+    transform: translateX(100%);
+  }
+}
diff --git a/src/components/skeleton/skeleton.tsx b/src/components/skeleton/skeleton.tsx
new file mode 100644
index 0000000..1c65c33
--- /dev/null
+++ b/src/components/skeleton/skeleton.tsx
@@ -0,0 +1,27 @@
+import type { HTMLAttributes } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './skeleton.module.scss';
+
+export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
+  variant?: 'text' | 'rect' | 'circle';
+  width?: number | string;
+  height?: number | string;
+}
+
+export function Skeleton({
+  variant = 'text',
+  width,
+  height,
+  className,
+  style,
+  ...props
+}: SkeletonProps) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(styles.skeleton, styles[variant], className)}
+      style={{ width, height, ...style }}
+      {...props}
+    />
+  );
+}
diff --git a/src/components/spinner/index.ts b/src/components/spinner/index.ts
new file mode 100644
index 0000000..602e374
--- /dev/null
+++ b/src/components/spinner/index.ts
@@ -0,0 +1,2 @@
+export { Spinner } from './spinner';
+export type { SpinnerProps } from './spinner';
diff --git a/src/components/spinner/spinner.module.scss b/src/components/spinner/spinner.module.scss
new file mode 100644
index 0000000..17e7952
--- /dev/null
+++ b/src/components/spinner/spinner.module.scss
@@ -0,0 +1,44 @@
+@use '../../styles/tokens' as *;
+@use '../../styles/mixins' as *;
+
+.spinner {
+  display: inline-flex;
+  vertical-align: middle;
+}
+
+.ring {
+  box-sizing: border-box;
+  border-style: solid;
+  border-color: color-mix(in srgb, var(--fui-text) 18%, transparent);
+  border-top-color: var(--fui-accent);
+  border-radius: 999px;
+  animation: fui-spin 0.7s linear infinite;
+
+  @include reduced-motion {
+    animation-duration: 1.8s;
+  }
+}
+
+.sm .ring {
+  width: 16px;
+  height: 16px;
+  border-width: 2px;
+}
+
+.md .ring {
+  width: 24px;
+  height: 24px;
+  border-width: 3px;
+}
+
+.lg .ring {
+  width: 40px;
+  height: 40px;
+  border-width: 4px;
+}
+
+@keyframes fui-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
diff --git a/src/components/spinner/spinner.tsx b/src/components/spinner/spinner.tsx
new file mode 100644
index 0000000..d78e7ba
--- /dev/null
+++ b/src/components/spinner/spinner.tsx
@@ -0,0 +1,16 @@
+import type { OutputHTMLAttributes } from 'react';
+import { cn } from '../../utils/style-helpers';
+import styles from './spinner.module.scss';
+
+export interface SpinnerProps extends OutputHTMLAttributes<HTMLOutputElement> {
+  size?: 'sm' | 'md' | 'lg';
+  label?: string;
+}
+
+export function Spinner({ size = 'md', label = 'Loading', className, ...props }: SpinnerProps) {
+  return (
+    <output aria-label={label} className={cn(styles.spinner, styles[size], className)} {...props}>
+      <span className={styles.ring} />
+    </output>
+  );
+}
diff --git a/src/index.ts b/src/index.ts
index f1c7c2f..c6d522b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -63,4 +63,13 @@ export type { AlertProps, AlertVariant } from './components/alert';
 export { Divider } from './components/divider';
 export type { DividerProps } from './components/divider';
 
+export { Spinner } from './components/spinner';
+export type { SpinnerProps } from './components/spinner';
+
+export { Progress } from './components/progress';
+export type { ProgressProps } from './components/progress';
+
+export { Skeleton } from './components/skeleton';
+export type { SkeletonProps } from './components/skeleton';
+
 export { cn } from './utils/style-helpers';

From 4235927c8e0f8afd6e2ddf9e79cb2426ac1c2e0c Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 18:52:56 +0000
Subject: [PATCH 09/10] ci: auto-create a draft PR on first push to a plan
 branch

Copied from paper-camp: pushes to feat/*, fix/*, refactor/*, chore/*,
docs/* branches named with an idea id (e.g. feat/idea-9-select) get a
draft PR via the Scout app if none exists. Direct pushes to main are
untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/draft-pr.yml | 64 ++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 .github/workflows/draft-pr.yml

diff --git a/.github/workflows/draft-pr.yml b/.github/workflows/draft-pr.yml
new file mode 100644
index 0000000..1f40d1e
--- /dev/null
+++ b/.github/workflows/draft-pr.yml
@@ -0,0 +1,64 @@
+name: Draft PR
+
+on:
+  push:
+    branches:
+      - feat/*
+      - fix/*
+      - refactor/*
+      - chore/*
+      - docs/*
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  draft-pr:
+    name: Draft PR
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Generate Scout app token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.SCOUT_APP_ID }}
+          private-key: ${{ secrets.SCOUT_PRIVATE_KEY }}
+          permission-contents: read
+          permission-pull-requests: write
+
+      - name: Create draft PR if not exists
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+          BRANCH: ${{ github.ref_name }}
+        run: |
+          PLAN_ID=$(echo "$BRANCH" | grep -oP '[a-z]+-\d+' || true)
+          if [ -z "$PLAN_ID" ]; then
+            echo "Branch '$BRANCH' does not match plan-ID pattern — skipping PR creation"
+            exit 0
+          fi
+
+          TITLE=$(echo "$BRANCH" | sed 's|^[^/]*/||' | sed 's/^[a-z]*-[0-9]*-//' | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g')
+          DISPLAY_ID=$(echo "$PLAN_ID" | sed 's/^\([a-z]*\)/\U\1/' | sed 's/\-[a-z]/\U&/')
+          FULL_TITLE="${DISPLAY_ID}: ${TITLE}"
+
+          EXISTING=$(gh pr list --head "$BRANCH" --state all --json number --jq '.[0].number' 2>/dev/null || echo "")
+
+          if [ -z "$EXISTING" ]; then
+            BODY="**Plan:** \`${DISPLAY_ID}\` — see \`papercamp/ideas/${DISPLAY_ID}.md\` for the full idea and its plan."
+            BODY="${BODY}"$'\n\n'"This PR was auto-created as a draft on the first push to this feature branch."
+            BODY="${BODY}"$'\n'"Promote to \"Ready for review\" when the plan reaches \`review\` status."
+            gh pr create \
+              --title "$FULL_TITLE" \
+              --body "$BODY" \
+              --draft \
+              --base main
+            echo "Created draft PR for $FULL_TITLE"
+          else
+            echo "PR #$EXISTING already exists for branch '$BRANCH' — skipping"
+          fi

From 740c0453321872fec952d8e9f69ee078f30d4228 Mon Sep 17 00:00:00 2001
From: Croco Dendy <croooco.dendy@gmail.com>
Date: Tue, 4 Aug 2026 18:54:14 +0000
Subject: [PATCH 10/10] ci: take only the first plan-id match when titling the
 draft PR

Branch slugs containing a second word-digit token (e.g. "tier-2")
made grep return multiple matches and mangled the PR title with a
newline. head -1 keeps the leading idea id.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/draft-pr.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/draft-pr.yml b/.github/workflows/draft-pr.yml
index 1f40d1e..e0ea0c6 100644
--- a/.github/workflows/draft-pr.yml
+++ b/.github/workflows/draft-pr.yml
@@ -37,7 +37,7 @@ jobs:
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
           BRANCH: ${{ github.ref_name }}
         run: |
-          PLAN_ID=$(echo "$BRANCH" | grep -oP '[a-z]+-\d+' || true)
+          PLAN_ID=$(echo "$BRANCH" | grep -oP '[a-z]+-\d+' | head -1 || true)
           if [ -z "$PLAN_ID" ]; then
             echo "Branch '$BRANCH' does not match plan-ID pattern — skipping PR creation"
             exit 0