Switch DESIGN.md code tokens from italics to backticks

dahlia · dahlia · commit 69a1c495cb8d · 2026-04-29T12:08:16.000+09:00
CSS class names, HTML elements, attributes, properties, custom
property names, function names, types, and props are now wrapped
in backticks instead of italics, since italics in this project
are reserved for package names, file paths, font families, and
brand/concept names per AGENTS.md's markdown style guide.

Italics are kept on package names like @iconify-json/lucide and
@unocss/cli, font families like Inter or Noto Sans KR, file
paths like src/components/Layout.tsx, and brand/concept names
like Wind4 or Lucide.

The "Variant groups" section is also rewritten to document the
project's actual policy: variant group shorthand is not used
because it leaks into HTML class attributes and triggers false
positive class matches.

Assisted-by: Claude Code:claude-opus-4-7
diff --git a/DESIGN.md b/DESIGN.md
@@ -57,22 +57,22 @@ Color system
 ### Neutral palette
 
 The default surface is achromatic.  Hollo uses UnoCSS's *Wind4* neutral
-scale (*neutral-50* through *neutral-950*) for backgrounds, borders,
+scale (`neutral-50` through `neutral-950`) for backgrounds, borders,
 surfaces, and text.  No saturation enters a page until a theme color is
 applied.
 
 | Role            | Light scheme  | Dark scheme   |
 | --------------- | ------------- | ------------- |
-| Page background | *neutral-50*  | *neutral-950* |
-| Surface         | *white*       | *neutral-900* |
-| Subtle border   | *neutral-200* | *neutral-800* |
-| Body text       | *neutral-900* | *neutral-100* |
-| Muted text      | *neutral-500* | *neutral-400* |
+| Page background | `neutral-50`  | `neutral-950` |
+| Surface         | `white`       | `neutral-900` |
+| Subtle border   | `neutral-200` | `neutral-800` |
+| Body text       | `neutral-900` | `neutral-100` |
+| Muted text      | `neutral-500` | `neutral-400` |
 
 ### Account theme colors
 
 Each account owner picks a theme color from a fixed set of twenty named
-hues, defined as the *theme\_color* PostgreSQL enum in *src/schema.ts*:
+hues, defined as the `theme_color` PostgreSQL enum in *src/schema.ts*:
 
 ~~~~
 amber  azure  blue   cyan    fuchsia  green   grey    indigo
@@ -81,20 +81,21 @@ slate  violet yellow zinc
 ~~~~
 
 The palette comes from Pico CSS's named color palette.  Each hue is
-expressed at nine tonal stops (*50, 100, 200, 300, 400, 500, 600, 700,
-800, 900*), stored as RGB triples in *src/theme/colors.ts*.
+expressed at nine tonal stops (`50`, `100`, `200`, `300`, `400`, `500`,
+`600`, `700`, `800`, `900`), stored as RGB triples in
+*src/theme/colors.ts*.
 
 ### CSS variable injection
 
 The theme color is applied through CSS custom properties on the
-`<html>` element.  *Layout.tsx* reads the account's *themeColor* and
+`<html>` element.  *Layout.tsx* reads the account's `themeColor` and
 emits inline declarations:
 
 ~~~~ html
 <html style="--theme-50:247 248 250; --theme-100:...; ... --theme-900:...">
 ~~~~
 
-The UnoCSS configuration exposes these variables as a generic *brand*
+The UnoCSS configuration exposes these variables as a generic `brand`
 color token:
 
 ~~~~ ts
@@ -118,15 +119,16 @@ varies with the theme color.
 
 Wind4 wraps every brand-colored utility in
 `color-mix(in srgb, ... var(--un-bg-opacity), transparent)`, so a
-`--un-bg-opacity` (and the matching `--un-text-opacity`, `--un-border-opacity`,
-`--un-ring-opacity`, `--un-divide-opacity`, `--un-placeholder-opacity`) custom
-property must be defined before any brand utility resolves.  *uno.config.ts*
-sets all of these to `100%` on *:root* via a preflight, which makes plain
-`bg-brand-500` behave like fully opaque rgb.
+`--un-bg-opacity` (and the matching `--un-text-opacity`,
+`--un-border-opacity`, `--un-ring-opacity`, `--un-divide-opacity`,
+`--un-placeholder-opacity`) custom property must be defined before any
+brand utility resolves.  *uno.config.ts* sets all of these to `100%` on
+`:root` via a preflight, which makes plain `bg-brand-500` behave like
+fully opaque rgb.
 
-Slash modifiers work as expected on top of this default: `bg-brand-500/50`,
-`text-brand-700/80`, `ring-brand-200/40`, and so on resolve to a 50%/80%/40%
-mix against transparent.
+Slash modifiers work as expected on top of this default:
+`bg-brand-500/50`, `text-brand-700/80`, `ring-brand-200/40`, and so on
+resolve to a 50%/80%/40% mix against transparent.
 
 ### Dark mode
 
@@ -147,61 +149,61 @@ Typography
 | Sans CJK | *Noto Sans KR*, *Noto Sans JP*, *Noto Sans SC* | bunny.net                 |
 | Mono     | *JetBrains Mono*                               | bunny.net                 |
 
-Fonts are loaded through UnoCSS's *presetWebFonts* with the *bunny*
+Fonts are loaded through UnoCSS's `presetWebFonts` with the `bunny`
 provider, which is a privacy-respecting mirror of Google Fonts.  The CSS
 font stack lists Inter first, then the three Noto Sans CJK families, and
 falls back to the system stack so initial paint never blocks on a
 network request.
 
 ### Type scale
 
-Use the Wind4 default scale unchanged (*text-xs* through *text-5xl*).
-Body copy is *text-base* with *leading-relaxed*.  Headings step down by
+Use the Wind4 default scale unchanged (`text-xs` through `text-5xl`).
+Body copy is `text-base` with `leading-relaxed`.  Headings step down by
 one level per nesting depth.
 
 ### Long-form content
 
 Rendered Markdown — post bodies, account bio fields, reply chains — is
-wrapped in the *prose* class from *presetTypography*, with
-*prose-neutral* and *dark:prose-invert* variants.  Inline code uses the
+wrapped in the `prose` class from `presetTypography`, with
+`prose-neutral` and `dark:prose-invert` variants.  Inline code uses the
 mono family; block code is rendered through Shiki and keeps its own
 colors.
 
 
 Spacing and layout
 ------------------
 
-The spacing scale is Wind4's default 4 px grid.  Use multiples of *2*
-(*0.5rem*), *3*, *4*, *6*, *8*, *12*, and *16* for almost all gaps.
+The spacing scale is Wind4's default 4 px grid.  Use multiples of `2`
+(`0.5rem`), `3`, `4`, `6`, `8`, `12`, and `16` for almost all gaps.
 
 Page widths:
 
- -  Reading column (post body, profile bio, settings forms): *max-w-2xl*
-    (~42 rem).
- -  Dashboard column (timelines, account list): *max-w-3xl* (~48 rem).
- -  Wide chrome (top nav, footer): full width with internal *max-w-5xl*.
+ -  Reading column (post body, profile bio, settings forms):
+    `max-w-2xl` (~42 rem).
+ -  Dashboard column (timelines, account list): `max-w-3xl` (~48 rem).
+ -  Wide chrome (top nav, footer): full width with internal `max-w-5xl`.
 
-Breakpoints follow the Wind4 defaults (*sm* 640 px, *md* 768 px, *lg*
-1024 px, *xl* 1280 px).  Mobile is the design start point; widen by
+Breakpoints follow the Wind4 defaults (`sm` 640 px, `md` 768 px, `lg`
+1024 px, `xl` 1280 px).  Mobile is the design start point; widen by
 adding `md:` and `lg:` variants.
 
 
 Iconography
 -----------
 
 Hollo uses a single icon collection: *Lucide*, surfaced through
-UnoCSS's *presetIcons* with the *@iconify-json/lucide* package.  Icons
+UnoCSS's `presetIcons` with the *@iconify-json/lucide* package.  Icons
 are written as CSS classes:
 
 ~~~~ tsx
 <span class="i-lucide-bell text-lg" aria-hidden="true" />
 ~~~~
 
-Sizing follows the surrounding text size by default (*1em*).  Icons
-inherit *currentColor*, so they tint with the parent's text color
+Sizing follows the surrounding text size by default (`1em`).  Icons
+inherit `currentColor`, so they tint with the parent's text color
 (including the theme color where applicable).  Decorative icons get
 `aria-hidden="true"`; meaningful icons have a paired text label or
-*aria-label*.
+`aria-label`.
 
 
 Components
@@ -224,8 +226,8 @@ ring and disabled state.
 
 ### Form field
 
-Each field is a labelled stack: *label → control → optional hint or
-error*.  Labels are above the control, never floating.  Required fields
+Each field is a labelled stack: label → control → optional hint or
+error.  Labels are above the control, never floating.  Required fields
 get a small “required” badge to the right of the label rather than an
 asterisk.  Errors are red and live below the control.
 
@@ -237,10 +239,10 @@ right.  On small screens the center links collapse into a sheet.
 
 ### Card and article
 
-Posts and notifications are rendered as *articles* — semantic HTML, no
-visible card border.  A subtle bottom divider separates each entry in a
-list.  Avatar, display name, handle, timestamp, and content stack
-vertically on mobile and arrange into a media object on *md*.
+Posts and notifications are rendered as `<article>` elements — semantic
+HTML, no visible card border.  A subtle bottom divider separates each
+entry in a list.  Avatar, display name, handle, timestamp, and content
+stack vertically on mobile and arrange into a media object on `md`.
 
 ### Avatar
 
@@ -254,7 +256,7 @@ version, and a link to the source.  No social icons.
 
 ### Empty state
 
-Centred icon (Lucide), one-line headline, optional subline, optional
+Centered icon (Lucide), one-line headline, optional subline, optional
 primary call-to-action.  No illustrations.
 
 
@@ -264,11 +266,11 @@ Motion
 Motion is reserved for state feedback, not decoration.  Allowed
 transitions:
 
- -  *colors*: 150 ms, on hover and focus changes.
- -  *opacity*: 150 ms, on disclosure toggles.
- -  *transform: scale*: 100 ms, on press of a button.
+ -  `colors`: 150 ms, on hover and focus changes.
+ -  `opacity`: 150 ms, on disclosure toggles.
+ -  `transform: scale`: 100 ms, on press of a button.
 
-Disable all transitions when *prefers-reduced-motion: reduce* is set.
+Disable all transitions when `prefers-reduced-motion: reduce` is set.
 Page transitions and route animations don't exist; SSR renders the new
 page directly.
 
@@ -277,16 +279,16 @@ Accessibility
 -------------
 
  -  Maintain WCAG AA contrast in both light and dark schemes.  Theme
-    colors pass contrast against neutral surfaces at the *600* and
-    *700* stops; lighter stops are background-only.
- -  Every focusable element has a visible *focus-visible* ring (a 2 px
-    ring in *brand-500* or *neutral-500*, offset by 2 px).
- -  Use semantic HTML: *button* for buttons, *a* for navigation,
-    *form*/*fieldset*/*label* for forms, *article* for individual posts,
-    *nav* for navigation regions.
- -  The *html* element's *lang* attribute reflects the page locale where
-    a content language is known.
- -  Decorative imagery uses *alt=“”* or *aria-hidden*.  Meaningful
+    colors pass contrast against neutral surfaces at the `600` and
+    `700` stops; lighter stops are background-only.
+ -  Every focusable element has a visible `:focus-visible` ring (a 2 px
+    ring in `brand-500` or `neutral-500`, offset by 2 px).
+ -  Use semantic HTML: `<button>` for buttons, `<a>` for navigation,
+    `<form>`/`<fieldset>`/`<label>` for forms, `<article>` for individual
+    posts, `<nav>` for navigation regions.
+ -  The `<html>` element's `lang` attribute reflects the page locale
+    where a content language is known.
+ -  Decorative imagery uses `alt=""` or `aria-hidden`.  Meaningful
     imagery has descriptive alternative text.
 
 
@@ -297,40 +299,39 @@ Implementation guide
 
 UnoCSS scans every *.tsx* and *.ts* file under *src/* via *@unocss/cli*
 and writes a single static stylesheet to *src/public/uno.css*.  In
-development, *concurrently* runs the UnoCSS watcher alongside *tsx
-watch*.  In production, *pnpm build* runs *unocss* once before *tsdown*.
-The stylesheet is served as a static asset, not bundled with the
-application code, and the Layout component links it like any other
-*.css* file.
+development, *concurrently* runs the UnoCSS watcher alongside `tsx watch`.  In
+production, `pnpm build` runs `unocss` once before `tsdown`. The stylesheet is
+served as a static asset, not bundled with the application code, and the Layout
+component links it like any other *.css* file.
 
 ### Layout shell
 
-*src/components/Layout.tsx* is the only place that emits *html*, *head*,
-and *body*.  Pages return a Layout-wrapped tree from their handler.
-Layout is responsible for:
+*src/components/Layout.tsx* is the only place that emits `<html>`,
+`<head>`, and `<body>`.  Pages return a Layout-wrapped tree from their
+handler.  Layout is responsible for:
 
 1.  Linking */public/uno.css*.
 2.  Computing the inline CSS variable string from the requested
-    *themeColor* and putting it on *html*.
-3.  Setting *lang*, page metadata (title, OG tags, canonical), and
+    `themeColor` and putting it on `<html>`.
+3.  Setting `lang`, page metadata (title, OG tags, canonical), and
     favicons.
 
 ### Theme tokens
 
-*src/theme/colors.ts* exports a frozen object mapping each
-*ThemeColor* enum value to its 50–900 RGB triples.  When changing the
-palette, edit only this file; nothing else needs to know about the
-twenty hues by name.
+*src/theme/colors.ts* exports a frozen object mapping each `ThemeColor`
+enum value to its 50–900 RGB triples.  When changing the palette, edit
+only this file; nothing else needs to know about the twenty hues by
+name.
 
 ### Forms
 
 Forms use the small helper components in *src/components/forms.tsx*:
 
- -  *Field* — wraps a control with a label, optional hint, and error
- -  *TextField*, *TextareaField*, *SelectField* — labelled controls
- -  *CheckboxField* — checkbox with adjacent label and hint
- -  *FieldSection* — card-shaped *fieldset* with a legend
- -  *SubmitButton* — primary/secondary/danger submit variants
+ -  `Field` — wraps a control with a label, optional hint, and error
+ -  `TextField`, `TextareaField`, `SelectField` — labelled controls
+ -  `CheckboxField` — checkbox with adjacent label and hint
+ -  `FieldSection` — borderless `<fieldset>` with a legend
+ -  `SubmitButton` — primary/secondary/danger submit variants
 
 These compose plain HTML controls with the agreed UnoCSS classes; they
 never wrap a third-party input library.  Reach for them first; only
@@ -339,18 +340,15 @@ express (the OTP field, for example, intentionally diverges).
 
 ### Prose content
 
-Apply the *prose prose-neutral dark:prose-invert* class set to the
-container that holds rendered Markdown.  Don't apply *prose* to
+Apply the `prose prose-neutral dark:prose-invert` class set to the
+container that holds rendered Markdown.  Don't apply `prose` to
 arbitrary blocks of UI; it is intended for long-form text only.
 
-### Variant groups
+### Variant group syntax
 
-The UnoCSS *variantGroup* transformer is enabled.  Group related
-variants:
-
-~~~~ tsx
-<button class="rounded-md px-4 py-2 (bg-brand text-white hover:bg-brand-600 focus-visible:ring-2 focus-visible:ring-brand-500)">
-~~~~
-
-Use this judiciously; long flat class lists are still fine when they
-are easier to read.
+Variant group shorthand (`focus:(border-brand-500 ring-2)`) is **not**
+used in this project.  `transformerVariantGroup` only expands the
+shorthand at class extraction time, but the original string still ships
+in the HTML `class` attribute, where the browser splits it on
+whitespace and matches `ring-2` (etc.) as a standalone class.  Always
+write each variant out long-form (`focus:border-brand-500 focus:ring-2 …`).
