@design-ai/cli 4.55.0

package/examples/component-biometric-gate.md

@@ -0,0 +1,281 @@
+# `BiometricGate` (custom — Korean mobile fintech) — spec
+
+> Custom component pattern. Required for Korean fintech / banking apps. No upstream design system has this — it's a domain-specific composition over OS APIs.
+>
+> Cited knowledge: [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md), [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md), [`knowledge/platforms/react-native.md`](../knowledge/platforms/react-native.md)
+
+## Purpose
+
+Gates app entry (or a sensitive flow) behind biometric authentication: Face ID / Touch ID (iOS), fingerprint / face recognition (Android).
+
+Korean financial apps **almost universally implement this**. Users have come to expect it for any app touching money — banking, fintech, payments, asset management. Skipping it makes the app feel insecure or unfinished.
+
+## When to use
+
+| Use case | Required? |
+| --- | --- |
+| App open (banking, KakaoPay, Toss) | Strongly expected by users |
+| Before transfer / payment | Common (configurable per user) |
+| Before viewing sensitive details (account number, balance) | Sometimes |
+| Before changing payment methods | Sometimes |
+| Before changing security settings | Yes |
+| First-time setup | No — biometric is enrolled later |
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│                                         │
+│           [App logo]                    │
+│                                         │
+│           [biometric icon]              │   ← face/fingerprint icon
+│              (~80px)                    │
+│                                         │
+│         Face ID로 인증해 주세요          │   ← title
+│         (또는 Touch ID / 지문)           │
+│                                         │
+│                                         │
+│         [📱 Face ID 사용]                │   ← primary CTA
+│         [비밀번호로 로그인]               │   ← fallback
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| App logo | optional | Reassures user this is the legitimate app |
+| Biometric icon | yes | Matches the available method (face / fingerprint) |
+| Title | yes | "Face ID로 인증해 주세요" or device-appropriate |
+| Description | optional | Explanation if needed |
+| Primary CTA | yes | Triggers the OS biometric prompt |
+| Fallback CTA | yes | Password / PIN login (always provide) |
+
+## API
+
+```tsx
+<BiometricGate
+  required
+  fallbackMethod="pin"
+  onSuccess={() => navigate("/dashboard")}
+  onFallback={() => navigate("/login/pin")}
+  onCancel={() => navigate("/login")}
+  reason="개인 정보 보호를 위해 인증이 필요합니다"
+  appLogo={<Logo />}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `required` | `boolean` | `true` | If false, allow skip via close button |
+| `fallbackMethod` | `"pin" \| "password" \| "pattern" \| "none"` | `"pin"` | Backup auth method |
+| `onSuccess` | `() => void` | — | Called when biometric succeeds |
+| `onFallback` | `() => void` | — | Called when user picks fallback |
+| `onCancel` | `() => void` | — | (When `required: false`) close pressed |
+| `reason` | `string` | — | Shown to user; also passed to OS prompt as the reason |
+| `autoTrigger` | `boolean` | `true` | Trigger OS prompt on mount automatically |
+| `appLogo` | `ReactNode` | — | Decorative logo |
+| `errorText` | `string` | — | Error after a failed attempt |
+
+## OS integration
+
+### iOS (React Native)
+
+```ts
+import * as LocalAuthentication from "expo-local-authentication";
+
+const triggerBiometric = async () => {
+  const isCompatible = await LocalAuthentication.hasHardwareAsync();
+  const isEnrolled = await LocalAuthentication.isEnrolledAsync();
+  if (!isCompatible || !isEnrolled) {
+    onFallback();
+    return;
+  }
+
+  const result = await LocalAuthentication.authenticateAsync({
+    promptMessage: reason || "본인 확인",
+    fallbackLabel: "비밀번호로 로그인",
+    cancelLabel: "취소",
+    disableDeviceFallback: false,
+  });
+
+  if (result.success) onSuccess();
+  else if (result.error === "user_cancel") onCancel();
+  else if (result.error === "user_fallback") onFallback();
+  else setErrorText("인증에 실패했습니다");
+};
+```
+
+### Android (React Native)
+
+Same `expo-local-authentication` API; falls back to fingerprint or face on supported devices.
+
+### Web
+
+Web's `WebAuthn` API exists but is rarely used in Korean consumer apps. For web fintech: typically a 6-digit PIN or 본인인증 (PASS / SMS) instead.
+
+This spec primarily targets **mobile native apps** (React Native or platform native).
+
+## Behavior
+
+### On mount
+
+1. Component renders with biometric icon + CTA.
+2. If `autoTrigger: true`: OS prompt opens immediately.
+3. User completes biometric → `onSuccess`.
+4. User cancels → `onCancel` (or stay on screen if `required`).
+5. User picks "Use password" → `onFallback`.
+
+### After failed attempt
+
+- iOS: 3 failed attempts disable biometric for that session; user must use fallback.
+- Android: similar; OS handles lockout.
+- Update `errorText` with "인증에 실패했습니다. 비밀번호를 사용해 주세요."
+- Don't auto-retry. User decides.
+
+### After lockout (5+ failures)
+
+- Biometric disabled until app is reopened.
+- Prompt user to use the fallback method.
+- Optionally: log out and require full sign-in.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Idle (waiting for trigger) | Icon + CTA visible |
+| Authenticating | Icon pulsing or spinner overlay |
+| Success | Brief checkmark, then navigate (or instant navigate) |
+| Failed | Error text below icon, CTA re-enabled to retry |
+| Locked out | "Biometric unavailable" text, fallback only |
+| OS prompt visible | Component is dimmed; OS handles input |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-text-primary
+--color-text-secondary
+--color-primary-default      (icon, primary CTA)
+--color-error                (error state)
+--color-success              (success checkmark)
+--space-lg, --space-xl, --space-2xl
+--font-size-xl, --font-size-2xl
+--motion-default             (icon pulse, success checkmark)
+```
+
+## Accessibility
+
+- Title is `<h1>` — primary message of the screen.
+- Biometric icon: `aria-hidden="true"` (decorative, the title carries meaning).
+- CTA button: clear `aria-label` if icon-only ("Use Face ID to sign in").
+- Fallback button: visible label, easy to find — don't bury it.
+- Error text: `role="alert"` so screen reader announces.
+- For users who can't use biometric: fallback path must be accessible without going through the biometric prompt.
+
+## Korean copy patterns
+
+| Method | Title (KR) |
+| --- | --- |
+| Face ID (iOS) | "Face ID로 인증해 주세요" |
+| Touch ID (iOS) | "Touch ID로 인증해 주세요" |
+| Fingerprint (Android) | "지문으로 인증해 주세요" |
+| Face (Android) | "얼굴 인식으로 인증해 주세요" |
+| Generic | "본인 확인" / "생체 인증" |
+
+| Action | Korean |
+| --- | --- |
+| Use Face ID | Face ID 사용 |
+| Use fingerprint | 지문 사용 |
+| Use password | 비밀번호로 로그인 |
+| Use PIN | PIN 입력 |
+| Cancel | 취소 |
+| Try again | 다시 시도 |
+
+## Code example
+
+```tsx
+function AppLaunchGate() {
+  const navigate = useNavigation();
+  const [error, setError] = useState<string>();
+
+  const handleSuccess = () => navigate("/dashboard");
+  const handleFallback = () => navigate("/login/pin");
+
+  return (
+    <BiometricGate
+      required
+      autoTrigger
+      reason="대시보드를 보려면 인증이 필요합니다"
+      fallbackMethod="pin"
+      onSuccess={handleSuccess}
+      onFallback={handleFallback}
+      errorText={error}
+      appLogo={<Logo />}
+    />
+  );
+}
+
+// As an action gate (not full screen)
+function TransferConfirm() {
+  const [showGate, setShowGate] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setShowGate(true)}>송금하기</Button>
+      {showGate && (
+        <BiometricGate
+          required={false}
+          reason="송금을 위해 본인 확인이 필요합니다"
+          onSuccess={() => { setShowGate(false); executeTransfer(); }}
+          onCancel={() => setShowGate(false)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+## Edge cases
+
+- **Biometric not enrolled** (user hasn't set up Face ID / fingerprint on device): show fallback as primary, with explanation.
+- **Biometric hardware not available** (older device): same — fallback only.
+- **User has enrolled but disabled biometric for this app** in OS settings: show fallback + link to settings.
+- **Background return** (user backgrounds app, returns): re-trigger gate based on app's session policy (typically 30 sec timeout).
+- **Multiple biometric methods on Android** (face + fingerprint): OS prompt handles selection. Don't try to manage in app.
+- **Server-side rejection** (biometric ok locally but server doesn't accept token): show error and route to fallback. Treat as auth failure, not biometric failure.
+- **Network offline at gate**: this is local auth — should work offline. The token is verified later when network returns.
+- **First time biometric on this device**: prompt before triggering ("Use Face ID for faster sign-in?") — don't surprise the user with an OS prompt cold.
+
+## Korean app submission considerations
+
+Per [`knowledge/i18n/korean-publishing.md`](../knowledge/i18n/korean-publishing.md):
+
+- iOS: `NSFaceIDUsageDescription` in `Info.plist` must be in Korean for KR storefront ("Face ID를 사용하여 안전하게 로그인합니다.").
+- Android: permission `USE_BIOMETRIC` (or `USE_FINGERPRINT` for older API). Permission rationale popup required for KR Play Store.
+- App Store Connect: privacy policy must mention biometric data (even though it's processed on-device).
+
+## Don't
+
+- Don't make biometric the **only** auth method. Always provide fallback.
+- Don't auto-trigger biometric on every screen — user fatigue.
+- Don't trigger biometric without user-initiated action (e.g., on app launch is OK; mid-scrolling is not).
+- Don't process biometric data on server. Per OS APIs, biometric verification is on-device; the server gets a token, not biometric data.
+- Don't gate trivial actions behind biometric. Reserve for sensitive operations.
+- Don't show biometric on web without a serious WebAuthn implementation. Use PIN / 본인인증 instead.
+- Don't store biometric "results" in app state beyond the session. Re-prompt next session.
+- Don't omit privacy disclosure (Korean law requires it).
+
+## API rationale
+
+- **`required: true` default**: matches user expectation for fintech app launch. False is the in-app action gate case.
+- **`autoTrigger: true` default**: a screen with biometric should immediately attempt — making the user tap the button first adds a step.
+- **`fallbackMethod` typed**: PIN / password / pattern are the realistic options. "None" rare and discouraged.
+- **`reason` passed to OS prompt**: iOS shows this as the prompt subtitle. Be specific.
+
+## Cross-reference
+
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — biometric expectations in KR
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — payment auth context
+- [`knowledge/i18n/korean-publishing.md`](../knowledge/i18n/korean-publishing.md) — privacy disclosure requirements
+- [`knowledge/platforms/react-native.md`](../knowledge/platforms/react-native.md) — RN-specific implementation
+- [`examples/component-modal.md`](component-modal.md) — focus management when as inline gate

package/examples/component-blockquote.md

@@ -0,0 +1,153 @@
+# `Blockquote` — spec
+
+> Doc-specific. For attributed quotations from other people. Distinct from `Callout` (which is editor-flagged content).
+
+## Purpose
+
+Render a quotation visually distinct from body text. Cite the source. Used in long-form articles, research reports (user quotes), case studies (customer quotes).
+
+## Anatomy
+
+```
+   "
+   The quote text, often slightly larger and styled
+   distinctly from body. May span multiple lines.
+   "
+
+   — Attribution name, role
+```
+
+OR with bar accent:
+
+```
+│  The quote text. Bar on left signals quote.
+│
+│  — Attribution name
+```
+
+## API
+
+```jsx
+<Blockquote>
+  <p>The quote text.</p>
+  <Blockquote.Cite>Attribution name, role</Blockquote.Cite>
+</Blockquote>
+
+// Or with the cite prop
+<Blockquote cite="https://example.com/source">
+  The quote text.
+</Blockquote>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Quote content |
+| `cite` | `string` | — | Source URL (renders as `<cite>` element) |
+| `variant` | `"default" \| "pull-quote"` | `"default"` | |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+
+## Variants
+
+### Default
+
+Inline within reading flow:
+
+```
+> Body text body text body text...
+> 
+> "The quote text."
+> — Source
+> 
+> Body text continues...
+```
+
+### Pull-quote
+
+Larger, often centered, breaks up dense reading:
+
+```
+        "The quote text — larger,
+         emphasized, distinct."
+
+         — Source
+```
+
+Used in editorial / marketing prose to surface a key sentiment.
+
+## Sizes
+
+| Size | Font | Body context |
+| --- | --- | --- |
+| `sm` | matches body | Inline mention |
+| `md` (default) | 1.125× body | Standard quote |
+| `lg` (pull-quote) | 1.5× body | Editorial breaking-out |
+
+## Style choices
+
+| Style cue | Use |
+| --- | --- |
+| Italic body | Latin convention. Don't use for Hangul. |
+| Larger size | Universal — signals quote |
+| Left bar (border-left) | Modern, clean |
+| Quote marks (large) | Editorial / marketing |
+| Centered text | Pull-quote variant |
+| Subtle bg tint | Differentiation in dense layouts |
+
+For Korean: don't italicize (no italic Hangul). Use weight (`font-weight: 500`) or color shift.
+
+## Tokens consumed
+
+```
+--color-text-primary
+--color-text-secondary       (attribution)
+--color-text-tertiary
+--color-border-default       (left bar)
+--color-bg-subtle             (optional bg tint)
+--space-md, --space-base
+--font-size-base, --font-size-lg, --font-size-xl
+--font-weight-medium
+```
+
+## Accessibility
+
+- Use semantic `<blockquote>` element. Ships with implicit role.
+- Attribution: `<cite>` element. Renders as italic by default; override per language.
+- Cite URL: optional `cite` attribute on `<blockquote>` for machine-readable source.
+
+```html
+<blockquote cite="https://example.com/source">
+  <p>The quote text.</p>
+  <footer><cite>— Source name</cite></footer>
+</blockquote>
+```
+
+## Korean conventions
+
+For quotations:
+- Use double quotes `" "` or angle quotes `「 」` — double Latin is most common in modern Korean docs.
+- Attribution: `— 이름` or `— 이름, 직책`.
+- Don't italicize (Hangul has no italic form). Use weight or color.
+
+```html
+<blockquote>
+  <p>"이 디자인은 정말 신선합니다."</p>
+  <cite>— 김민지, 디자인 디렉터</cite>
+</blockquote>
+```
+
+## Don't
+
+- Don't italicize Hangul.
+- Don't omit attribution. An unattributed quote is suspicious.
+- Don't use blockquote for non-quotations (rule, tip, note — those are Callouts).
+- Don't nest blockquotes. Quote-in-a-quote is rare; use prose.
+
+## References
+
+Universal HTML element. Most doc tools render `<blockquote>` consistently. Style varies.
+
+## Cross-reference
+
+- [`examples/component-callout.md`](component-callout.md) — for editor flags, not quotes
+- [`knowledge/patterns/document-typography.md`](../knowledge/patterns/document-typography.md) — pull-quote rules
+- [`knowledge/patterns/report-design.md`](../knowledge/patterns/report-design.md) — research quote patterns

package/examples/component-border-beam.md

@@ -0,0 +1,207 @@
+# `BorderBeam` — spec
+
+> Synthesized from Ant Design `BorderBeam`, with host-surface guidance cross-checked against MUI `Paper` / `Card` and shadcn-ui `Card`. `BorderBeam` is a decorative emphasis layer, not a semantic status, focus, or validation border.
+
+## When to use
+
+- A single container needs controlled visual emphasis: featured AI panel, recommended card, login panel, onboarding highlight, or primary dashboard module.
+- The surface already has a clear semantic role and the beam only increases visual salience.
+- The child host is a real DOM element or a component that forwards its ref to a DOM element.
+
+When NOT to use:
+- Validation, focus, selected, error, success, warning, or destructive state. Use semantic border/status tokens instead.
+- Dense dashboards with many cards. More than one or two beams on a viewport reads as noise.
+- Motion-sensitive or high-focus workflows where a moving border competes with reading or data entry.
+- Containers whose root cannot provide a stable DOM ref, position context, or border radius.
+
+## Anatomy
+
+```
+BorderBeam
+├── Child host element
+│   ├── Existing surface content
+│   └── Beam effect layer (portal, aria-hidden)
+└── Gradient / inset / radius CSS variables
+```
+
+| Part | Purpose | Required | Default if omitted |
+| --- | --- | --- | --- |
+| Child host | The decorated element that receives the portal layer. | yes | Plain text or non-ref children render without the beam. |
+| Beam effect layer | Absolutely-positioned visual border effect inside the host. | internal | Hidden until browser support and host resolution pass. |
+| Gradient | Beam color or gradient stops. | no | Uses primary theme gradient. |
+| Inset offset | Moves the effect outward from the host edge. | no | Inferred from host border width. |
+| Radius bridge | Mirrors the host border radius for alignment. | internal | Reads computed radius during initialization. |
+
+## API
+
+```tsx
+<BorderBeam
+  color={[
+    { color: "var(--color-primary-default)", percent: 0 },
+    { color: "var(--color-accent-default)", percent: 100 },
+  ]}
+  outset={0}
+>
+  <section className="featured-panel">
+    <h2>AI review ready</h2>
+    <p>3 design-system risks need review.</p>
+  </section>
+</BorderBeam>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Decorated content. Must resolve to a single host DOM element for the beam to render. |
+| `color` | `string \| { color: string; percent: number }[]` | theme primary gradient | Solid beam color or ordered gradient stops. `percent` is authored as `0` to `100`; implementation maps it into the visible beam segment. |
+| `outset` | `number \| string` | host border width | Offset from the container edge. Use `0` when the host clips overflow or already owns a visible border. |
+| `className` | `string` | — | Class applied to the beam effect layer, not the child host. |
+| `style` | `CSSProperties` | — | Inline styles for the beam effect layer, including custom CSS variables. |
+| `prefixCls` | `string` | design-system prefix | Advanced namespace override. Prefer provider-level configuration. |
+
+## API choices made
+
+- Keep the API intentionally small. `BorderBeam` should decorate a surface; it should not become a full Card variant system.
+- Keep `color` as either one semantic token string or explicit gradient stops. Do not add `intent="success"` / `intent="error"` because that would imply semantic status.
+- Treat `outset` as an alignment escape hatch. Most product code should rely on host border inference or set `outset={0}` for clipped cards.
+- Do not expose speed, direction, or looping props by default. Constant decorative motion should be rare, reduced-motion-safe, and globally governed by motion tokens.
+
+## States
+
+| State | Trigger | Visual / behavior |
+| --- | --- | --- |
+| Default | Host resolves and browser supports required CSS masking / offset-path | Beam layer renders around the host, `pointer-events: none`, `aria-hidden="true"`. |
+| Unsupported CSS | Browser lacks mask or offset-path support | Beam stays hidden; child content remains unchanged. |
+| Missing host | Plain text, fragment, non-ref component, or SVG child | Beam is skipped; child content still renders. |
+| Hover | Pointer over host | No built-in change. Host component may own its normal hover state. |
+| Focus-visible | Keyboard focus on host or child control | Beam must not replace the 2px focus ring. Focus ring keeps at least 3:1 contrast per `keyboard-and-focus.md`. |
+| Active | Pointer / keyboard activation on host content | No built-in change. Interactive child components own active feedback. |
+| Disabled | Disabled content inside host | Beam should usually be removed; a disabled surface should not attract attention. |
+| Loading | Async content inside host | Keep only if it helps identify the active module; never use the beam as loading progress. |
+| Error | Error content inside host | Remove or recolor through semantic error UI; do not use decorative beam as the only error indicator. |
+| Reduced motion | `prefers-reduced-motion: reduce` | Hide the moving effect or freeze it into a non-moving border highlight. |
+
+## Variants
+
+### Emphasis level
+
+| Level | Use | Visual rule |
+| --- | --- | --- |
+| `subtle` | Secondary highlight, recommendation card | Low-opacity token gradient, no extra shadow. |
+| `default` | One primary featured surface | Primary to accent gradient, one beam per viewport region. |
+| `campaign` | Marketing or onboarding hero module | Stronger gradient is allowed, but still respects reduced motion and contrast. |
+
+### Host surface
+
+| Host | Rule |
+| --- | --- |
+| Card / Paper | Put radius and `position: relative` on the actual root element. |
+| Button / link card | Keep the focus ring outside or above the beam; do not rely on the beam for focus. |
+| Modal / dialog | Avoid except for onboarding. Motion around modal edges can distract from the task. |
+| Data table / form | Avoid. Continuous motion is disruptive for scanning and input. |
+
+## Tokens consumed
+
+```css
+--color-primary-default
+--color-primary-hover
+--color-accent-default
+--color-focus-ring
+--color-border-emphasis
+--radius-md
+--radius-lg
+--border-width-sm
+--motion-duration-slow
+--motion-easing-linear
+```
+
+If your design system does not have `--color-border-emphasis`, map the default beam to primary/accent tokens and keep semantic status tokens separate.
+
+## Accessibility
+
+- **Semantics**: the beam layer is decorative and must render with `aria-hidden="true"`.
+- **Keyboard**: `BorderBeam` itself is not focusable and adds no keyboard behavior. Any interactive child keeps its native keyboard contract.
+- **Focus**: never use the moving beam as focus indication. Interactive descendants need a visible 2px focus ring with at least 3:1 contrast against adjacent colors.
+- **Reduced motion**: hide the moving beam for `prefers-reduced-motion: reduce`, or replace it with a static border. This follows `motion/principles.md`.
+- **Pointer behavior**: the effect layer uses `pointer-events: none` so it cannot block clicks, text selection, or hover states on the host.
+- **Contrast**: because the beam is decorative, it does not carry required information. If a design uses border color to communicate state, provide text/icon redundancy and at least 3:1 non-text contrast.
+- **Screen readers**: no announcement is needed for beam appearance. Announce only the actual state or content change inside the host.
+- **Touch target**: if the decorated host is interactive, keep the host target at least 44x44 on mobile and at least 24x24 for WCAG 2.2 AA web minimum.
+
+## Code example — featured module
+
+```tsx
+type FeaturedModuleProps = {
+  title: string;
+  description: string;
+  action: React.ReactNode;
+};
+
+export function FeaturedModule({ title, description, action }: FeaturedModuleProps) {
+  return (
+    <BorderBeam
+      color={[
+        { color: "var(--color-primary-default)", percent: 0 },
+        { color: "var(--color-accent-default)", percent: 100 },
+      ]}
+      outset={0}
+    >
+      <section className="featured-module" aria-labelledby="featured-module-title">
+        <div>
+          <h2 id="featured-module-title">{title}</h2>
+          <p>{description}</p>
+        </div>
+        {action}
+      </section>
+    </BorderBeam>
+  );
+}
+```
+
+```css
+.featured-module {
+  position: relative;
+  overflow: hidden;
+  border: 1px solid var(--color-border-subtle);
+  border-radius: var(--radius-lg);
+  background: var(--color-bg-elevated);
+}
+
+.featured-module:focus-within {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ant-border-beam::before {
+    display: none;
+  }
+}
+```
+
+## Edge cases
+
+- **Non-ref child**: function components must forward a ref to the real DOM root, or the beam cannot mount.
+- **Plain text / fragment**: render content without decoration. Do not wrap automatically because it can change layout and semantics.
+- **Static positioning**: the beam may inject, but deterministic placement needs `position: relative` on the host.
+- **Overflow clipping**: use `outset={0}` when the host has `overflow: hidden`; negative offsets can be clipped unpredictably.
+- **Changing radius**: radius is read during initialization. If responsive or state-driven radius changes matter, set the final radius on the host before mount or remount the decorated host.
+- **Custom gradient stops**: clamp authored `percent` to `0..100`; preserve a transparent tail so the beam has a visible fade.
+- **RTL**: the decorative direction does not need semantic mirroring. If brand motion direction matters, define it in the motion system rather than per component.
+- **Print**: hide the beam in print; decorative motion and gradients do not belong on invoices, reports, or contracts.
+- **Korean B2B sensitive-data surfaces**: use sparingly. One highlighted review panel is acceptable; continuous decoration around HR or payroll forms can reduce perceived seriousness.
+
+## Don't
+
+- Don't use `BorderBeam` as a substitute for focus-visible, selected, validation, or status borders.
+- Don't decorate every card in a grid.
+- Don't pass literal brand hex values in product code; use semantic color tokens.
+- Don't wrap a component that cannot forward a DOM ref and then treat the missing beam as a rendering bug.
+- Don't animate around long-form reading, tables, or data-entry forms unless the user explicitly requested a guided highlight.
+
+## References
+
+- Ant Design: [`BorderBeam.tsx`](../refs/ant-design/components/border-beam/BorderBeam.tsx), [`BorderBeamEffect.tsx`](../refs/ant-design/components/border-beam/BorderBeamEffect.tsx), [`border-beam/index.en-US.md`](../refs/ant-design/components/border-beam/index.en-US.md), [`border-beam/style/index.ts`](../refs/ant-design/components/border-beam/style/index.ts)
+- MUI: [`Paper.d.ts`](../refs/mui/packages/mui-material/src/Paper/Paper.d.ts), [`Card.d.ts`](../refs/mui/packages/mui-material/src/Card/Card.d.ts)
+- shadcn-ui: [`card.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/card.tsx)
+- Knowledge: [`a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md), [`motion/principles.md`](../knowledge/motion/principles.md), [`components/INDEX.md`](../knowledge/components/INDEX.md)
+- Cross-reference: [`component-card.md`](component-card.md), [`component-paper.md`](component-paper.md), [`component-button-base.md`](component-button-base.md)