@k8ordo/ui 1.0.0 → 2.1.0

package/docs/references/spatial-design.md

@@ -1,137 +1,159 @@
-# スペーシング・レイアウト
+# Spacing and layout
 
-k8ordo UI は「余白で語る」デザイン。詰め込まず、空間にゆとりを持たせる。
+`@k8ordo/ui` is a design that lets the spacing speak. Do not pack things in;
+leave room.
 
-## スペーシングの原則
+## Spacing principles
 
-4pt ベースのスペーシングシステム。Tailwind の標準スケールを使用。
+A 4pt spacing system: one token, `--spacing` (0.25rem), multiplied by the step
+you want — `calc(var(--spacing) * 6)` is 1.5rem. With `tailwind.css`, the
+step is the utility's number (`p-6`, `gap-8`).
 
-### コンポーネント内部パディング
+### Padding inside a component
 
-| 用途           | クラス | 値   |
-| -------------- | ------ | ---- |
-| コンパクト     | `p-4`  | 16px |
-| 標準           | `p-6`  | 24px |
-| ゆったり       | `p-8`  | 32px |
-| 大きなカード内 | `p-10` | 40px |
+| Use               | Step | Value |
+| ----------------- | ---- | ----- |
+| Compact           | 4    | 16px  |
+| Standard          | 6    | 24px  |
+| Generous          | 8    | 32px  |
+| Inside a big card | 10   | 40px  |
 
-### テキスト間の余白
+### Spacing between blocks of text
 
-| 関係性         | クラス  | 用途                         |
-| -------------- | ------- | ---------------------------- |
-| 近い要素       | `mt-2`  | 説明テキスト、ヘルプテキスト |
-| 標準           | `mt-4`  | 段落間、フォームフィールド間 |
-| セクション間   | `mt-8`  | セクション区切り             |
-| 大セクション間 | `mt-12` | ページレベルの区切り         |
+| Relationship           | Step | Use                                     |
+| ---------------------- | ---- | --------------------------------------- |
+| Closely related        | 2    | Descriptions, help text                 |
+| Standard               | 4    | Between paragraphs, between form fields |
+| Between sections       | 8    | A section break                         |
+| Between major sections | 12   | A page-level break                      |
 
-### セクション間の余白
+### Spacing between sections
 
-| 関係性       | クラス              | 用途                       |
-| ------------ | ------------------- | -------------------------- |
-| カード間     | `gap-6`             | 横並びカード（グリッド内） |
-| セクション間 | `gap-8` 〜 `gap-10` | 縦に並ぶセクション         |
+| Relationship     | Step   | Use                            |
+| ---------------- | ------ | ------------------------------ |
+| Between cards    | 6      | Cards side by side (in a grid) |
+| Between sections | 8 – 10 | Sections stacked vertically    |
 
-## 角丸
+## Border radius
 
-**「触れるものは柔らかく、読むものは端正に」**
+**"Soft where you touch, precise where you read."**
 
-要素の性格に応じて角丸を使い分ける。
+Vary the radius with the element's role.
 
-### 触れるもの（柔らかく）
+### Things you touch (soft)
 
-| 用途                          | クラス         | 値     |
-| ----------------------------- | -------------- | ------ |
-| Button                        | `rounded-full` | ピル型 |
-| Input, Textarea, Select       | `rounded-xl`   | 1rem   |
-| Card, CheckboxCard, RadioCard | `rounded-xl`   | 1rem   |
+| Use                           | Token           | Value |
+| ----------------------------- | --------------- | ----- |
+| Button                        | `--radius-full` | Pill  |
+| Input, Textarea, Select       | `--radius-xl`   | 1rem  |
+| Card, CheckboxCard, RadioCard | `--radius-xl`   | 1rem  |
 
-### 読むもの（端正に）
+### Things you read (precise)
 
-| 用途     | クラス         | 値                           |
-| -------- | -------------- | ---------------------------- |
-| Alert    | `rounded-lg`   | 0.75rem                      |
-| Badge    | `rounded-full` | ピル型（小さいので問題ない） |
-| Tabs     | 現行のまま     |                              |
-| Checkbox | `rounded-md`   | 0.5rem                       |
+| Use      | Token           | Value                          |
+| -------- | --------------- | ------------------------------ |
+| Alert    | `--radius-lg`   | 0.75rem                        |
+| Callout  | `--radius-lg`   | 0.75rem                        |
+| Badge    | `--radius-full` | Pill (fine, since it is small) |
+| Tabs     | As-is           |                                |
+| Checkbox | `--radius-md`   | 0.5rem                         |
 
-### その他
+### Everything else
 
-| 用途                               | クラス         |
-| ---------------------------------- | -------------- |
-| Dialog, Modal                      | `rounded-lg`   |
-| Avatar, IconButton, プログレスバー | `rounded-full` |
+| Use                              | Token           |
+| -------------------------------- | --------------- |
+| Dialog, Modal                    | `--radius-lg`   |
+| Avatar, IconButton, progress bar | `--radius-full` |
 
-## シャドウ
+With `tailwind.css` these are `rounded-full`, `rounded-xl`, … .
 
-ふんわり柔らかい影で奥行きを表現する。
+## Shadow
 
-| 用途                     | スタイル                                                |
-| ------------------------ | ------------------------------------------------------- |
-| Card（デフォルト）       | `shadow-sm`（appearance="shadow" 時）                   |
-| Card（ボーダー）         | `border border-border-mute`（appearance="bordered" 時） |
-| Modal / Dialog / Tooltip | `shadow-md`                                             |
-| Dropdown / ListBox       | `shadow-md`                                             |
-| Button                   | なし                                                    |
+Express depth with a soft, gentle shadow.
 
-`shadow-xl` 以上は使わない。
+| Use                      | Style                                                    |
+| ------------------------ | -------------------------------------------------------- |
+| Card (default)           | `--shadow-sm` (with `variant="shadow"`)                  |
+| Card (outlined)          | a 1px `--color-border-mute` border (`variant="outline"`) |
+| Modal / Dialog / Tooltip | `--shadow-md`                                            |
+| Dropdown / ListBox       | `--shadow-md`                                            |
+| Button                   | None                                                     |
 
-## ページ構造
+Never use `--shadow-xl` or heavier. The focus ring is a shadow too,
+`--shadow-ring-info`; with a surface's own shadow, list the ring first:
+`box-shadow: var(--shadow-ring-info), var(--shadow-xs)`.
 
-### bg-subtle + 白カードの基本パターン
+## Page structure
 
-ページ背景を `bg-bg-subtle`（薄いグレー）にし、コンテンツを白いカードで浮かせる。
+### The bg-subtle plus white card pattern
+
+Make the page background `--color-bg-subtle` (a light grey) and float the
+content on white cards.
+
+```css
+.page {
+  min-height: 100vh;
+  background-color: var(--color-bg-subtle);
+}
+
+.body {
+  padding: calc(var(--spacing) * 6);
+}
+```
 
 ```tsx
-// Good: 灰色背景に白カードが浮く
-<div className="bg-bg-subtle min-h-screen">
-  <Card appearance="shadow">
-    <div className="p-8">コンテンツ</div>
+// Good: a white card floating on a grey ground
+<div className={styles.page}>
+  <Card variant="shadow">
+    <div className={styles.body}>Content</div>
   </Card>
 </div>
 ```
 
-### 余白で階層を作る
+### Build hierarchy out of spacing
 
-```tsx
-// Good: 余白の差で関連度を示す
-<section className="mt-12">
-  <Heading level="h2">セクション</Heading>
-  <p className="mt-2">直接関連する説明</p>
-  <div className="mt-8">やや離れたコンテンツ</div>
-</section>
-
-// Bad: すべて同じ余白
-<section className="mt-4">
-  <Heading level="h2">セクション</Heading>
-  <p className="mt-4">説明</p>
-  <div className="mt-4">コンテンツ</div>
-</section>
+Let the size of the gap show how related things are: 12 steps above a
+section, 2 between a heading and the description that belongs to it, 8 before
+content that sits a little apart. The same gap everywhere flattens the page.
+
+```css
+.section {
+  margin-top: calc(var(--spacing) * 12);
+}
+
+.description {
+  margin-top: calc(var(--spacing) * 2);
+}
+
+.content {
+  margin-top: calc(var(--spacing) * 8);
+}
 ```
 
-### カードは万能ではない
+### A card is not the answer to everything
 
-すべてのコンテンツをカードに入れる必要はない。余白とセパレーターで十分なケースが多い。
+Content does not have to go in a card. Spacing and a separator are often enough.
 
 ```tsx
 import { Separator } from '@k8ordo/ui';
 
-// Good: セパレーターで区切る
+// Good: divide with a separator (.divider { padding-block: calc(var(--spacing) * 8); })
 <div>
-  <section>コンテンツA</section>
-  <div className="py-8">
+  <section>Content A</section>
+  <div className={styles.divider}>
     <Separator />
   </div>
-  <section>コンテンツB</section>
+  <section>Content B</section>
 </div>
 
-// 過剰: すべてカードに入れる
-<Card>コンテンツA</Card>
-<Card>コンテンツB</Card>
+// Excessive: everything in a card
+<Card>Content A</Card>
+<Card>Content B</Card>
 ```
 
-## やってはいけないこと
+## What not to do
 
-- `gap-1` や `p-1` のような極端に狭いスペーシング
-- コンテンツの詰め込み（情報密度より余白を優先）
-- ネストされたカード（Card in Card）
-- 12 を超える z-index 値
+- Extremely tight spacing such as one step (`calc(var(--spacing) * 1)`)
+- Cramming content in (space wins over information density)
+- Nested cards (Card in Card)
+- A z-index of your own: stack with `--z-index-raised` (inside a component), `--z-index-overlay`, `--z-index-modal` and `--z-index-toast`

package/docs/references/types.md

@@ -0,0 +1,101 @@
+# Types
+
+The shared types `@k8ordo/ui` exports for typing component props.
+
+```tsx
+import type {
+  Direction,
+  DrawerSide,
+  ModalSide,
+  Option,
+  Placement,
+  Status,
+} from '@k8ordo/ui';
+```
+
+## Status
+
+```tsx
+type Status = 'success' | 'info' | 'warning' | 'error';
+```
+
+Used for the status of `Alert`, `Callout`, `Toast`, and `AlertIcon`. `Badge` takes its own `tone`, which also allows `'neutral'`.
+
+## Direction
+
+```tsx
+type Direction = 'up' | 'down' | 'right' | 'left';
+```
+
+Used to point ChevronIcon and similar icons.
+
+## Placement
+
+```tsx
+type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
+```
+
+Placement relative to an anchor element, for Popover, Tooltip, DropdownMenu,
+and ListBox (the `placement` prop), and for IconButton's tooltip
+(`tooltipPlacement`).
+
+## ModalSide
+
+```tsx
+type ModalSide = 'center' | 'bottom' | 'left' | 'right';
+```
+
+Which viewport edge a Modal sticks to (the `side` prop). It is a different
+idea from `Placement`, which is relative to an anchor, so the prop name differs
+too.
+
+## DrawerSide
+
+```tsx
+type DrawerSide = Extract<ModalSide, 'left' | 'right'>;
+```
+
+The subset of `ModalSide` a Drawer accepts: a drawer always slides in from an
+edge, so `center` is excluded.
+
+## Option
+
+```tsx
+type Option = Readonly<{ value: string; label: string }>;
+```
+
+Used for the choices in Radio, Select, Autocomplete, and similar components.
+
+## Component prop types
+
+The root also exports types that belong to one component, for typing your own
+code around it:
+
+| Type                                                                  | What it types                                                                                           |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `StackProps` / `GridProps`                                            | Every prop of `Stack` / `Grid`, for a component that wraps one                                          |
+| `GapSize` / `PaddingSize`                                             | The `none`–`xl` scale of `gap` (Stack, Grid) and `padding` (Stack)                                      |
+| `ButtonRenderItemProps` / `IconButtonRenderItemProps`                 | What `renderItem` receives on `Button` / `IconButton`                                                   |
+| `IconButtonTriggerProps`                                              | `Partial<TooltipTriggerProps>`: the tooltip wiring in `IconButtonRenderItemProps`' `triggerProps`       |
+| `PopoverTriggerProps` / `PopoverContentProps` / `TooltipTriggerProps` | What `renderItem` receives on `Popover.Trigger` / `Popover.Content` / `Tooltip.Trigger`                 |
+| `ToolbarItemProps`                                                    | What `renderItem` receives on `Toolbar.Item`: `ref`, `tabIndex`, `onFocus`                              |
+| `CommandPaletteItem`                                                  | A command in `CommandPalette`: `id`, `label`, `onSelect`, plus `group`, `keywords`, `shortcut`          |
+| `AlertAction` / `ToastAction` / `ToastOptions`                        | `Alert`'s `action`, and the `action` and `duration` a toast takes                                       |
+| `ColorPickerSwatch`                                                   | A preset in `ColorPicker`'s `swatches`: `value` (`#rrggbb`) and `label`, the color's name               |
+| `ComboboxSearch`                                                      | `Combobox`'s `search`: `(query, { signal }) => Promise<readonly Option[]>`                              |
+| `CheckboxCardOption` / `RadioCardOption`                              | A choice in `CheckboxCard` / `RadioCard`: `value` and `label`, plus `description`, `visual`, `disabled` |
+| `StepperStep`                                                         | A step in `Stepper`: `label`, plus `description`                                                        |
+| `CellAlign`                                                           | A table cell's `align`: `'left'`, `'center'`, or `'right'`                                              |
+| `BaseIconProps` / `IconRenderProps`                                   | An icon's `size`, and the props an icon puts on its `<svg>`                                             |

package/docs/references/typography.md

@@ -1,110 +1,219 @@
-# タイポグラフィ
+# Typography
 
-k8ordo UI のタイポグラフィは「読みやすさ」と「静けさ」を両立する。
+Typography in `@k8ordo/ui` aims for readability and quiet at the same time.
 
-## フォントファミリー
+## Font family
 
-日本語最適化のフォントスタック。
+A font stack tuned for Japanese: Noto Sans JP and M PLUS 2.
+
+The library ships no font files and sets no font of its own: until your app
+sets one, text stays on the reset's system stack, `--font-family-sans`
+(Roboto included). Load the fonts yourself (fontsource, `next/font`, …), declare
+them as tokens, and set the body:
 
 ```css
-font-family: 'Noto Sans JP', 'M PLUS 2', sans-serif;
+:root {
+  --font-family-noto-sans-jp: 'Noto Sans JP', sans-serif;
+  --font-family-m-plus-2: 'M PLUS 2', sans-serif;
+}
+
+body {
+  font-family: var(--font-family-noto-sans-jp);
+}
 ```
 
-- **Inter / Roboto / Open Sans は使わない** — AI が生成した感が出る
-- 日本語テキストが主体のため、和文フォントを優先
+- `--font-family-sans` and `--font-family-mono` are the reset's stacks, which `body` and `code` / `kbd` / `pre` use until your app sets its own
+- With `tailwind.css`, `--font-family-noto-sans-jp` and `--font-family-m-plus-2` back the `font-noto-sans-jp` and `font-m-plus-2` utilities. They are the only font-family utilities; the theme removes `font-sans`, `font-serif`, and `font-mono`
+- **Do not use Inter / Roboto / Open Sans** — they read as AI-generated
+- Japanese text dominates, so Japanese faces come first
+
+## Font size scale
+
+Each size has a line height to go with it, `--line-height-<size>`
+(`--font-size-sm` with `--line-height-sm`). With `tailwind.css`, `text-<size>`
+sets both.
+
+| Token                   | Value    | Use                     |
+| ----------------------- | -------- | ----------------------- |
+| `--font-size-xs`        | 0.75rem  | Annotations, captions   |
+| `--font-size-sm`        | 0.875rem | Supporting text, labels |
+| `--font-size-md`        | 1rem     | Body text (default)     |
+| `--font-size-lg`        | 1.125rem | Subheadings             |
+| `--font-size-xl`        | 1.25rem  | Headings                |
+| `--font-size-2xl`       | 1.5rem   | Large headings          |
+| `--font-size-3xl`       | 1.875rem | Page titles             |
+| `--font-size-emphasize` | 3rem     | Emphasis display        |
+| `--font-size-highlight` | 6rem     | Highlight display       |
 
-## フォントサイズスケール
+Three sizes follow the text they sit in, in `em`: `--font-size-code` (0.875em,
+code in running text), `--font-size-kbd` (0.8125em) and `--font-size-callout`
+(0.9em, the notes of a `CodeBlock`). `--spacing-em` (0.25em) is the spacing step
+that goes with them.
 
-| Tailwind クラス  | 値       | 用途                 |
-| ---------------- | -------- | -------------------- |
-| `text-xs`        | 0.75rem  | 注釈、キャプション   |
-| `text-sm`        | 0.875rem | 補足テキスト、ラベル |
-| `text-md`        | 1rem     | 本文（デフォルト）   |
-| `text-lg`        | 1.125rem | 小見出し             |
-| `text-xl`        | 1.25rem  | 見出し               |
-| `text-2xl`       | 1.5rem   | 大見出し             |
-| `text-3xl`       | 1.875rem | ページタイトル       |
-| `text-emphasize` | 3rem     | 強調表示             |
-| `text-highlight` | 6rem     | ハイライト表示       |
+## Font weight
 
-## フォントウェイト
+Use weight sparingly. Heavy type undermines the quiet.
 
-ウェイトは控えめに使う。太字の多用は「静けさ」を損なう。
+| Token                  | Value | Use                                   |
+| ---------------------- | ----- | ------------------------------------- |
+| (none)                 | 400   | Body text (the inherited default)     |
+| `--font-weight-medium` | 450   | Emphasized text (restrained emphasis) |
+| `--font-weight-bold`   | 700   | Headings, button labels               |
 
-| Tailwind クラス | 値  | 用途                         |
-| --------------- | --- | ---------------------------- |
-| `font-normal`   | 400 | 本文                         |
-| `font-medium`   | 450 | 強調テキスト（控えめな強調） |
-| `font-bold`     | 700 | 見出し、ボタンラベル         |
+- There are only these two weight tokens. With `tailwind.css`, `font-medium` and `font-bold` are the only weight utilities
+- Note that `--font-weight-medium` is 450 here — lighter than the usual 500
 
-- `font-semibold` (600) や `font-extrabold` (800) は使わない
-- `font-medium` が 450 であることに注意（一般的な 500 より軽い）
+## Line height
 
-## 行間
+Japanese text needs more leading than Latin text.
 
-日本語テキストは欧文より広い行間が必要。
+| Token                   | Value | Use                             |
+| ----------------------- | ----- | ------------------------------- |
+| `--line-height-none`    | 1     | Special cases (highlight, …)    |
+| `--line-height-tight`   | 1.25  | Headings                        |
+| `--line-height-snug`    | 1.375 | Subheadings                     |
+| `--line-height-normal`  | 1.5   | Inside lists; the default       |
+| `--line-height-relaxed` | 1.625 | Body text (recommended)         |
+| `--line-height-loose`   | 2     | When wide leading is called for |
 
-| Tailwind クラス   | 値    | 用途                     |
-| ----------------- | ----- | ------------------------ |
-| `leading-none`    | 1     | 特殊用途（highlight 等） |
-| `leading-tight`   | 1.25  | 見出し                   |
-| `leading-snug`    | 1.375 | 小見出し                 |
-| `leading-normal`  | 1.5   | リスト内、デフォルト     |
-| `leading-relaxed` | 1.625 | 本文（推奨）             |
-| `leading-loose`   | 2     | 広い行間が必要な場合     |
+With `tailwind.css` these are `leading-none` … `leading-loose`.
 
-## 字間
+## Letter spacing
 
-| Tailwind クラス   | 値      | 用途             |
-| ----------------- | ------- | ---------------- |
-| `tracking-none`   | 0em     | デフォルト       |
-| `tracking-normal` | 0.025em | 少し広げたい場合 |
+| Token                     | Value   | Use                         |
+| ------------------------- | ------- | --------------------------- |
+| `--letter-spacing-none`   | 0em     | Default                     |
+| `--letter-spacing-normal` | 0.025em | When a little air is wanted |
 
-## Heading コンポーネント
+With `tailwind.css` these are `tracking-none` and `tracking-normal`.
 
-見出しには `Heading` コンポーネントを使う。
+## The Heading component
+
+Use the `Heading` component for headings.
 
 ```tsx
 import { Heading } from '@k8ordo/ui';
 
-<Heading level="h1">ページタイトル</Heading>
-<Heading level="h2">セクション見出し</Heading>
-<Heading level="h3">サブセクション</Heading>
+<Heading level="h1">Page title</Heading>
+<Heading level="h2">Section heading</Heading>
+<Heading level="h3">Subsection</Heading>
 ```
 
-## 縦書きモード
+## Long-form text (Prose)
 
-縦書き表示には専用のユーティリティと variant を用意している。
+The base styles reset headings, lists, margins, and emphasis, which is right for
+an interface and wrong for an article. `Prose` puts the typesetting of body text
+back inside it, for Markdown or MDX rendered to HTML:
 
-### ユーティリティ
+```tsx
+import { Prose } from '@k8ordo/ui';
 
-| Tailwind クラス | 用途                                                                                                        |
-| --------------- | ----------------------------------------------------------------------------------------------------------- |
-| `writing-h`     | 横書き (`writing-mode: horizontal-tb`) に戻す。縦書きツリー内の図表・コードブロック・置換要素などで使う。   |
-| `writing-v`     | 縦書き (`writing-mode: vertical-rl`) を適用し、`text-orientation: mixed` などの推奨初期値も一括で設定する。 |
+<article>
+  <Prose>{content}</Prose>
+</article>;
+```
 
-### `vertical:` variant
+What it sets, tuned for Japanese:
+
+- Body text on `--line-height-loose` (2) with `--letter-spacing-normal`:
+  Japanese needs more leading than Latin text.
+- `1rem` between blocks, `3rem` above an `h2`, `2rem` above `h3`–`h6`, and
+  `0.75rem` between a heading and what follows it.
+- Headings in `--font-weight-bold`, `--line-height-snug`, with
+  `text-wrap: balance` and proportional kana (`font-feature-settings: 'palt'`).
+- `strong` in `--font-weight-bold`. `em` as emphasis dots (傍点, `text-emphasis: filled
+  sesame`) where the text is Japanese (`:lang(ja)`), and italic elsewhere.
+- Links, inline code, `kbd`, and `pre` drawn like `Anchor`, `Code`, `Kbd`, and a
+  code block; lists with their markers back; quotes, tables, rules, images,
+  and GFM footnotes and task lists (the footnotes' `sr-only` heading is
+  read but not shown).
+- Under `.writing-v`, each paragraph's first line is indented one character,
+  as a book is set.
+
+**Only bare elements are typeset.** The element rules stop at any element with a
+`class` — which is every `@k8ordo/ui` component — so a component placed in the
+text keeps its own look (an `Alert`'s list does not get bullets). The spacing
+between blocks still applies to it. The classes remark-gfm puts on footnotes
+and task lists (`footnotes`, `contains-task-list`, `task-list-item`,
+`data-footnote-backref`, `sr-only`) are the exception: they are treated as part
+of the text.
+Map an MDX element to a component when you want it to look like the component,
+and leave it bare when you want it to look like text.
+
+## Vertical writing mode
+
+`styles.css` ships three classes for the writing mode. They are the public
+markers the components read, not utilities: put them on the element that
+should turn.
+
+| Class                 | Use                                                                                                                                                                                    |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `writing-h`           | Return to horizontal (`writing-mode: horizontal-tb`). Use it for figures, code blocks, and replaced elements inside a vertical tree.                                                   |
+| `writing-v`           | Apply vertical writing (`writing-mode: vertical-rl`) together with the recommended defaults such as `text-orientation: mixed`.                                                         |
+| `writing-sideways-rl` | Turn a block sideways (`writing-mode: sideways-rl`): it lays out like horizontal text rotated 90° clockwise, Japanese glyphs included. `Table` turns itself this way in vertical text. |
+
+### Styling for vertical text
+
+`writing-v` and `writing-h` also set the custom property `--writing`
+(`vertical` or `horizontal`; `:root` holds `horizontal`), and it inherits. Read
+it with a style query to change your own styles in vertical text:
 
-`.writing-v` 子孫で活性化し、`.writing-h` 子孫では無効化する Tailwind variant。横書きデフォルトに対する上書きを宣言的に書ける。
+```css
+.paragraph {
+  margin-block: calc(var(--spacing) * 4);
 
-```tsx
-<div className="writing-v">
-  <p className="my-4 vertical:my-0">
-    {/* 横書き時のみ縦マージン、縦書きでは外す */}
-  </p>
-</div>
+  @container style(--writing: vertical) {
+    margin-block: 0;
+  }
+}
 ```
 
-### 注意点
+A style query asks the element's parent, so it does not see a `writing-v` on
+the element itself: style that element through a class of its own. Prefer
+logical properties (`margin-block`, `inline-size`) first; they often make the
+override unnecessary.
+
+With `tailwind.css`, the `vertical:` variant does the same for utilities: it
+applies inside a `.writing-v` subtree and not inside `.writing-h`
+(`className="my-4 vertical:my-0"`).
+
+### Switching at runtime
 
-- 画像・iframe などの置換要素は `vertical-rl` で大きさが想定通りにならないことがある。`<img className="vertical:writing-h" />` のように要素自体は横書きに戻す。
-- `-webkit-line-clamp` (`line-clamp-*`) は Safari で `writing-mode` と干渉する。縦書きでは `block-size` 上限 + `overflow: hidden` に置き換える。
-- KaTeX など内部で水平レイアウトを前提とするライブラリは、必要箇所だけ `writing-h` を上書きする。
+There is no JavaScript API for the writing mode. Keep the mode in your own
+state, and put `writing-v` on the container that should turn vertical:
 
-## やってはいけないこと
+```tsx
+const [mode, setMode] = useState<'horizontal' | 'vertical'>('horizontal');
+
+<article className={mode === 'vertical' ? 'writing-v' : undefined}>
+  <p className={styles.paragraph}>…</p>
+  <pre className="writing-h">…</pre>
+</article>;
+```
 
-- 3種類以上のフォントウェイトを1画面で使う
-- `text-3xl` より大きいサイズを通常テキストに使う（`text-emphasize` / `text-highlight` は特殊用途）
-- `uppercase` や `tracking-widest` を日本語テキストに適用する
-- テキストにグラデーションをかける
-- フォントサイズだけで階層を作る（余白も活用する）
+- Components follow a `.writing-v` ancestor on their own, with no props.
+  `Tabs` (arrow keys and `aria-orientation`) and `Autocomplete` (the width of
+  its list) also follow a class toggled while they are on screen. `Popover`,
+  `Tooltip`, `DropdownMenu`, and `ListBox` read the writing mode each time
+  they open, so a change made while one is open shows the next time it opens.
+- When your own JavaScript has to branch — hiding a side rail in vertical
+  mode, say — branch on the state you toggle, not on the DOM.
+- To read the mode of an element you do not control, call
+  `getComputedStyle(element).writingMode` at the moment you need it. There is
+  no event to subscribe to, and a `ResizeObserver` does not stand in for one:
+  an element that shrinks to fit its content keeps its logical size when the
+  writing mode flips, so the observer never fires.
+
+### Caveats
+
+- Replaced elements such as images and iframes may not size as expected under `vertical-rl`. Return the element itself to horizontal, as in `<img className="writing-h" />`.
+- `-webkit-line-clamp` conflicts with `writing-mode` in Safari. In vertical mode, replace it with a `block-size` cap plus `overflow: hidden`.
+- Libraries that assume horizontal layout internally, such as KaTeX, need `writing-h` applied only where required.
+
+## What not to do
+
+- Reach past the three weights (400, `--font-weight-medium`, `--font-weight-bold`) with an arbitrary value (`font-weight: 600`, …)
+- Use anything larger than `--font-size-3xl` for ordinary text (`--font-size-emphasize` and `--font-size-highlight` are for special cases)
+- Apply `text-transform: uppercase` or wide letter spacing to Japanese text
+- Apply a gradient to text
+- Build hierarchy from font size alone — use spacing as well