torch-glare-mcp 1.0.4 → 1.0.6

package/docs/components/alert-dialog.md

@@ -456,6 +456,166 @@ function PermissionAlert() {
 | `variant` | `ButtonVariant` | `'RedSecStyle'` | Button variant |
 | `buttonType` | `'button' \| 'icon'` | `'icon'` | Button type |
 
+## Known Limitations & Frontend Patterns
+
+### Every AlertDialog subcomponent ships without panel/typography defaults — and worse than `Dialog`
+
+`AlertDialogContent` ships with `p-[12px]` (too tight), `AlertDialogHeader` with `flex justify-between` (instead of `flex-col` for stacked title+description), `AlertDialogFooter` with `flex-col-reverse sm:flex-row` (vertical-on-mobile), and `AlertDialogDescription` with the bizarre `bg-background-presentation-form-base border ... rounded-[8px] p-[24px_48px_48px_48px]` — a 48 px-padded bordered box wrapped around what should be a one-line subtitle.
+
+**Production-tested override** — patch `AlertDialog.tsx` once after `npx torch-glare add AlertDialog`. Same surface-token corrections as `Dialog`: use `bg-background-presentation-body-primary` and `text-content-presentation-global-*`, never `*-system-*` and never `form-base`.
+
+```tsx
+"use client";
+
+import * as React from "react";
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
+import { cn } from "@/utils/cn";
+
+const AlertDialog = AlertDialogPrimitive.Root;
+const AlertDialogTrigger = AlertDialogPrimitive.Trigger;
+const AlertDialogPortal = AlertDialogPrimitive.Portal;
+
+const AlertDialogOverlay = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/60",
+      "data-[state=open]:animate-in data-[state=closed]:animate-out",
+      "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDialogOverlay.displayName = AlertDialogPrimitive.Overlay.displayName;
+
+const AlertDialogContent = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPortal>
+    <AlertDialogOverlay />
+    <AlertDialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 translate-x-[-50%] translate-y-[-50%]",
+        "flex flex-col items-stretch justify-start",
+        "w-[92vw] sm:max-w-md",
+        "bg-background-presentation-body-primary",
+        "border border-border-presentation-global-primary",
+        "rounded-xl shadow-lg",
+        "p-0 gap-0 overflow-hidden",
+        "duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out",
+        className,
+      )}
+      {...props}
+    />
+  </AlertDialogPortal>
+));
+AlertDialogContent.displayName = AlertDialogPrimitive.Content.displayName;
+
+const AlertDialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-col space-y-1.5 text-left px-6 pt-5 pb-2", className)}
+    {...props}
+  />
+);
+AlertDialogHeader.displayName = "AlertDialogHeader";
+
+const AlertDialogFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-row justify-end gap-2 px-6 py-4", className)}
+    {...props}
+  />
+);
+AlertDialogFooter.displayName = "AlertDialogFooter";
+
+const AlertDialogTitle = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "typography-headers-small-semibold text-content-presentation-global-primary",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDialogTitle.displayName = AlertDialogPrimitive.Title.displayName;
+
+const AlertDialogDescription = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Description
+    ref={ref}
+    className={cn(
+      "typography-body-small-regular text-content-presentation-global-secondary px-6 pb-2",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDialogDescription.displayName = AlertDialogPrimitive.Description.displayName;
+
+const AlertDialogAction = AlertDialogPrimitive.Action;
+const AlertDialogCancel = AlertDialogPrimitive.Cancel;
+
+export {
+  AlertDialog,
+  AlertDialogTrigger,
+  AlertDialogPortal,
+  AlertDialogOverlay,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+};
+```
+
+Critical default decisions:
+
+- **Drop the bordered box on `AlertDialogDescription`.** The shipped default wraps the description in a 48 px-padded bordered box, which produces a visually heavy nested panel. Description is a one-line subtitle — same typography pattern as `DialogDescription`.
+- **`AlertDialogHeader` → `flex flex-col` (NOT `flex justify-between`)** so title and description stack with proper rhythm.
+- **`AlertDialogFooter` → `flex-row justify-end`** on all viewports, no `flex-col-reverse sm:flex-row` weirdness.
+- **`AlertDialogDescription` carries `px-6 pb-2`** since alert dialogs typically don't have a separate body section between header and footer.
+- Surface and text tokens are **identical to `Dialog`** — `bg-background-presentation-body-primary` + `text-content-presentation-global-primary` + `text-content-presentation-global-secondary`. Never `*-system-*`. Never `form-base`. Never `action-secondary`.
+
+### Standard usage after the override
+
+Once the patches above are in place, every consumer renders correctly with bare components:
+
+```tsx
+<AlertDialog open={open} onOpenChange={setOpen}>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Delete this template?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone. The template will be permanently removed.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel asChild>
+        <Button type="button" variant="BorderStyle" size="M">Cancel</Button>
+      </AlertDialogCancel>
+      <AlertDialogAction asChild>
+        <Button type="button" variant="RedColStyle" size="M" onClick={handleDelete}>
+          Delete
+        </Button>
+      </AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
 ## Variants
 
 ### Default Variant

package/docs/components/date-picker.md

@@ -615,6 +615,31 @@ The `as unknown as Date` shape is required — TypeScript will reject `as Date`
 
 The shipped runtime uses `string` for `hour`, `minute`, and `time` (`"AM" | "PM"`). If you derive your own state from `TimePickerValue`, type those fields as `string`, not `number`, regardless of what older docs claim.
 
+### Internal `<Picker>` value/onChange types are incompatible with `TimePickerValue` — `tsc` fails out of the box
+
+`DatePicker.tsx` wraps `torch-react-mobile-picker`'s `<Picker>` and passes a concrete `TimePickerValue` (`{ hour, minute, time }`) where the picker's generic `PickerValue` (`Record<string, string>`) is expected. Strict TypeScript builds fail immediately:
+
+```
+DatePicker.tsx: Type 'TimePickerValue' is not assignable to type 'PickerValue'.
+  Index signature for type 'string' is missing in type 'TimePickerValue'.
+DatePicker.tsx: Type '(e: TimePickerValue) => void' is not assignable to type
+  '(value: PickerValue, key: string) => void'.
+```
+
+**Workaround — add `as any` casts at the `<Picker>` boundary** (and only there, so consumer types stay honest):
+
+```tsx
+<Picker
+  value={value as any}
+  onChange={((e: TimePickerValue) => {
+    onChange(e);
+  }) as any}
+  wheelMode="normal"
+>
+```
+
+Patch this manually after `npx torch-glare add DatePicker` — otherwise `pnpm build` (which runs `tsc -b`) will fail. The same `Ref` import in the file is also unused and trips `noUnusedLocals`; remove it while you're in there.
+
 ### `npx torch-glare add DatePicker` does not install `utils/dateFormat.ts`
 
 The CLI ships `DatePicker.tsx` without copying the `dateFormat.ts` utility it imports, so the component fails to build immediately after install:

package/docs/components/dialog.md

@@ -484,31 +484,63 @@ export const DialogCloseButton: React.ForwardRefExoticComponent<
 
 ## Known Limitations & Frontend Patterns
 
-### `DialogContent` ships without background, padding, border, or sizing
+### Every Dialog subcomponent ships without panel/typography defaults
 
-The base classes on the shipped `DialogContent` are missing every property a usable dialog panel needs — no background color (transparent), no padding (form fields flush against the edge), no border / rounded corners, `w-fit` (so the panel sizes to content), and no `max-height` / overflow handling. Out of the box, dialogs are visually broken and tall forms get cut off.
+`DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, and `DialogDescription` all ship without surfaces, padding, rounded corners, or theme-correct typography. The official "bare" example renders an invisible/transparent panel, and the shipped `DialogTitle` defaults to `text-content-system-global-primary` (a light-on-dark token) which renders white-on-white on the correct light surface.
 
-**Override pattern** — wrap or replace the shipped `DialogContent` with these defaults so you don't have to repeat them on every consumer:
+**Critical token corrections** (the previous override was wrong):
+
+- The right surface is `bg-background-presentation-body-primary` — NOT `bg-background-presentation-form-base` (form-base is for input field surfaces) and NOT `bg-background-system-action-secondary` (that's a brand-dark inverted action surface).
+- The right title token is `text-content-presentation-global-primary` — NOT `text-content-system-global-primary`.
+- The right description token is `text-content-presentation-global-secondary` — NOT the shipped triple-stack `"text-sm text-muted-foreground text-content-system-global-primary"`.
+
+**Production-tested override** — patch `Dialog.tsx` once after `npx torch-glare add Dialog`, then every consumer renders correctly with bare components:
 
 ```tsx
+"use client";
+
+import * as React from "react";
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { cn } from "@/utils/cn";
 
+const Dialog = DialogPrimitive.Root;
+const DialogTrigger = DialogPrimitive.Trigger;
+const DialogPortal = DialogPrimitive.Portal;
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/60",
+      "data-[state=open]:animate-in data-[state=closed]:animate-out",
+      "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className,
+    )}
+    {...props}
+  />
+));
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+
 const DialogContent = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
 >(({ className, children, ...props }, ref) => (
-  <DialogPrimitive.Portal>
-    <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-black/80" />
+  <DialogPortal>
+    <DialogOverlay />
     <DialogPrimitive.Content
       ref={ref}
       className={cn(
-        "fixed left-[50%] top-[50%] z-50 w-full max-w-lg translate-x-[-50%] translate-y-[-50%]",
-        "flex flex-col gap-4 p-6 rounded-2xl",
+        "fixed left-[50%] top-[50%] z-50 translate-x-[-50%] translate-y-[-50%]",
+        "flex flex-col items-stretch justify-start",
+        "w-[92vw] sm:max-w-lg",
+        "bg-background-presentation-body-primary",
         "border border-border-presentation-global-primary",
-        "bg-background-presentation-form-base",
-        "shadow-2xl",
-        "max-h-[90vh] overflow-y-auto",
+        "rounded-xl shadow-lg",
+        "p-0 gap-0 overflow-hidden",
+        "max-h-[90vh]",
         "duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out",
         className,
       )}
@@ -516,21 +548,115 @@ const DialogContent = React.forwardRef<
     >
       {children}
     </DialogPrimitive.Content>
-  </DialogPrimitive.Portal>
+  </DialogPortal>
+));
+DialogContent.displayName = DialogPrimitive.Content.displayName;
+
+const DialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-col space-y-1.5 text-left px-6 pt-5 pb-4", className)}
+    {...props}
+  />
+);
+DialogHeader.displayName = "DialogHeader";
+
+const DialogFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-row justify-end gap-2 px-6 py-4", className)}
+    {...props}
+  />
+);
+DialogFooter.displayName = "DialogFooter";
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "typography-headers-small-semibold text-content-presentation-global-primary",
+      className,
+    )}
+    {...props}
+  />
+));
+DialogTitle.displayName = DialogPrimitive.Title.displayName;
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cn(
+      "typography-body-small-regular text-content-presentation-global-secondary",
+      className,
+    )}
+    {...props}
+  />
 ));
+DialogDescription.displayName = DialogPrimitive.Description.displayName;
+
+export {
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogOverlay,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+};
 ```
 
-Critical defaults:
+Critical default decisions, and why:
+
+- **`bg-background-presentation-body-primary`** for the panel surface — it's the body-surface token that pairs correctly with `text-content-presentation-global-primary` across all themes. `form-base` and `action-secondary` are wrong choices that the previous version of this doc recommended.
+- **`p-0 gap-0 overflow-hidden`** on `DialogContent` — padding is delegated to `DialogHeader`/`DialogFooter` (and the form body). Keeping the content padding-free lets header/footer touch the rounded corners cleanly.
+- **`DialogHeader` → `flex flex-col space-y-1.5 ... px-6 pt-5 pb-4`** — column layout (NOT `flex justify-between` like the shipped default) so title and description stack with a tight 6 px gap. Padding lives here, not on the content.
+- **`DialogFooter` → `flex flex-row justify-end gap-2 px-6 py-4`** — horizontal on all viewports (NOT `flex-col-reverse sm:flex-row` like the shipped default). The shipped vertical-on-mobile pattern looks broken on narrow phones too.
+- **`w-[92vw] sm:max-w-lg`** — 92 % of viewport on mobile, 512 px max from `sm` up. Override per-dialog with `className="sm:max-w-110"` (440 px) or `sm:max-w-2xl` (672 px) for wider forms.
+
+### Form body lives outside the form-padded `DialogFooter`
+
+Place the `<form>` between `DialogHeader` and `DialogFooter`, with the footer as a **sibling outside the form** so its padding doesn't compound with the form body's padding. Use `type="button"` + `onClick={handleSubmit(onSubmit)}` on the submit button rather than `type="submit"`:
+
+```tsx
+<Dialog open={open} onOpenChange={onOpenChange}>
+  <DialogContent className="sm:max-w-110">
+    <DialogHeader>
+      <DialogTitle>Create Folder</DialogTitle>
+      <DialogDescription>Add a new folder.</DialogDescription>
+    </DialogHeader>
+
+    <form className="flex flex-col gap-4 px-6 py-5">
+      <LabelField
+        label="Folder Name"
+        requiredLabel="*"
+        {...register("name")}
+        className="w-full *:w-full"
+      />
+    </form>
+
+    <DialogFooter>
+      <Button type="button" variant="BorderStyle" size="M" onClick={() => onOpenChange(false)}>
+        Cancel
+      </Button>
+      <Button type="button" variant="PrimeStyle" size="M" onClick={handleSubmit(onSubmit)}>
+        Create
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
 
-- `bg-background-presentation-form-base` — solid background using the design token
-- `border border-border-presentation-global-primary rounded-2xl` — visible panel
-- `p-6` — sensible padding
-- `w-full max-w-lg` — consistent 512 px width; override per-dialog with `className="max-w-2xl"` etc.
-- `max-h-[90vh] overflow-y-auto` — long forms scroll instead of getting clipped
+The `px-6 py-5` body padding matches the header/footer's horizontal `px-6` rhythm so the columns line up vertically across the panel.
 
 ### `DialogTitle` with icon
 
-Plain `<DialogTitle>Create Account</DialogTitle>` lacks visual hierarchy. Standard pattern across production dialogs:
+Plain `<DialogTitle>Create Account</DialogTitle>` is fine, but you can pass JSX with an icon for instant entity recognition:
 
 ```tsx
 <DialogHeader>

package/docs/components/{section-card.md → section-block.md}

@@ -1,6 +1,6 @@
 ---
-name: SectionCard
-title: SectionCard
+name: SectionBlock
+title: SectionBlock
 description: Sectioned card container with a colored title badge for grouping related content like forms, tables, or lists.
 category: layout
 group: Layout & Containers
@@ -11,34 +11,34 @@ dependencies:
   - "class-variance-authority": "^0.7.0"
 ---
 
-# SectionCard
+# SectionBlock
 
 > A card container with an optional colored title badge. Use it to group related content — custom field forms, tables, settings groups — under a clear, color-coded heading.
 
 ## Installation
 
 ```bash
-npx torch-glare add SectionCard
+npx torch-glare add SectionBlock
 ```
 
 ## Import
 
 ```typescript
-import { SectionCard, type SectionColor } from "@/components/SectionCard";
+import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
 ```
 
 ## Basic Usage
 
 ```tsx
-import { SectionCard } from "@/components/SectionCard";
+import { SectionBlock } from "@/components/SectionBlock";
 
 export function Example() {
   return (
-    <SectionCard color="Blue" title="Project details">
+    <SectionBlock color="Blue" title="Project details">
       <p className="text-content-presentation-action-light-primary py-4">
         Card body content goes here.
       </p>
-    </SectionCard>
+    </SectionBlock>
   );
 }
 ```
@@ -71,7 +71,7 @@ export type SectionColor =
   | "Pink"
   | "Gray";
 
-export interface SectionCardProps
+export interface SectionBlockProps
   extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
   color?: SectionColor;
   title?: ReactNode;
@@ -81,14 +81,14 @@ export interface SectionCardProps
 }
 ```
 
-The component is a `forwardRef<HTMLDivElement, SectionCardProps>`.
+The component is a `forwardRef<HTMLDivElement, SectionBlockProps>`.
 
 ## Examples
 
 ### All Colors
 
 ```tsx
-import { SectionCard, type SectionColor } from "@/components/SectionCard";
+import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
 
 const COLORS: SectionColor[] = [
   "Blue",
@@ -105,11 +105,11 @@ export function AllColors() {
   return (
     <div className="flex flex-col gap-[24px]">
       {COLORS.map((color) => (
-        <SectionCard key={color} color={color} title={`${color} section`}>
+        <SectionBlock key={color} color={color} title={`${color} section`}>
           <p className="text-content-presentation-action-light-primary py-4">
             This is a {color.toLowerCase()} sectioned card.
           </p>
-        </SectionCard>
+        </SectionBlock>
       ))}
     </div>
   );
@@ -121,11 +121,11 @@ export function AllColors() {
 When `title` is omitted, the header is hidden but the body padding remains.
 
 ```tsx
-<SectionCard>
+<SectionBlock>
   <p className="text-content-presentation-action-light-primary py-4">
-    A SectionCard without a title — header is hidden, body still padded.
+    A SectionBlock without a title — header is hidden, body still padded.
   </p>
-</SectionCard>
+</SectionBlock>
 ```
 
 ### Rich Title with Icon
@@ -133,7 +133,7 @@ When `title` is omitted, the header is hidden but the body padding remains.
 `title` accepts any ReactNode, so you can pass JSX with icons, counts, links, etc.
 
 ```tsx
-<SectionCard
+<SectionBlock
   color="Purple"
   title={
     <span className="flex items-center gap-[6px]">
@@ -145,22 +145,22 @@ When `title` is omitted, the header is hidden but the body padding remains.
   <p className="text-content-presentation-action-light-primary py-4">
     The title prop is fully customizable.
   </p>
-</SectionCard>
+</SectionBlock>
 ```
 
 ### Custom Fields Form
 
-A common pattern: pair `SectionCard` with a row layout to build labeled-field forms.
+A common pattern: pair `SectionBlock` with a row layout to build labeled-field forms.
 
 ```tsx
 import { type ReactNode } from "react";
-import { SectionCard } from "@/components/SectionCard";
+import { SectionBlock } from "@/components/SectionBlock";
 import { InputField } from "@/components/InputField";
 import { ActionButton } from "@/components/ActionButton";
 
 export function CustomFieldsForm() {
   return (
-    <SectionCard
+    <SectionBlock
       color="Blue"
       title={
         <span className="flex items-center gap-[6px]">
@@ -203,7 +203,7 @@ export function CustomFieldsForm() {
           />
         }
       />
-    </SectionCard>
+    </SectionBlock>
   );
 }
 
@@ -241,7 +241,7 @@ function RowDivider() {
 Use `containerClassName`, `headerClassName`, and `bodyClassName` to override the built-in spacing and width without losing the title/body structure.
 
 ```tsx
-<SectionCard
+<SectionBlock
   color="Green"
   title="Compact card"
   containerClassName="w-[600px] pt-[4px] pb-[16px]"
@@ -250,14 +250,14 @@ Use `containerClassName`, `headerClassName`, and `bodyClassName` to override the
   <p className="text-content-presentation-action-light-primary py-2">
     Tighter, narrower variant.
   </p>
-</SectionCard>
+</SectionBlock>
 ```
 
 ## Patterns
 
 - **Color coding**: Use distinct colors to help users scan a page of multiple sections (e.g., Blue for primary forms, Yellow for warnings, Red for destructive zones).
 - **No-title sections**: Drop the `title` prop entirely when the section's purpose is obvious from context — keeps the body padding without the visual weight of a header.
-- **Composing with form fields**: `SectionCard` does not impose any inner layout — pair it with helpers like the `FieldRow` pattern above, or with `InputField`, `Form`, or `FieldSection` for more structured forms.
+- **Composing with form fields**: `SectionBlock` does not impose any inner layout — pair it with helpers like the `FieldRow` pattern above, or with `InputField`, `Form`, or `FieldSection` for more structured forms.
 - **Default width**: The component ships with `w-[1100px]`. Override via `containerClassName="w-full"` (or any specific width) for narrower containers.
 
 ## Accessibility

package/docs/components/toggle.md

@@ -373,6 +373,65 @@ interface CustomToggleProps extends ToggleProps, VariantProps<typeof toggleVaria
 export const Toggle: React.ForwardRefExoticComponent<CustomToggleProps>
 ```
 
+## Known Limitations & Frontend Patterns
+
+> ⚠️ **`Toggle` is icon-only.** Its dimensions are hardcoded squares — `S=22×22`, `M=28×28`, `L=34×34`, `XL=40×40` — so any text label wider than ~3 characters will visually clip. The "Filter Options", "Theme Switcher with text", and similar text-label examples below are misleading: they only render correctly in environments that override the dimensions.
+
+### Use `Button` with variant swap for selectable text chips
+
+For format selectors (DOCX, MD, RTF), tag pickers, filter pills, or any case where the chip carries text wider than ~3 characters, **do not use `Toggle`**. Use `Button` with a `variant` swap to express the selected state:
+
+```tsx
+const FORMATS = ["DOCX", "MD", "RTF", "ODT", "EPUB", "TXT"];
+
+export function FormatPicker({ selected, onSelect }: Props) {
+  return (
+    <div className="flex flex-wrap gap-2">
+      {FORMATS.map((format) => {
+        const isSelected = selected === format;
+        return (
+          <Button
+            key={format}
+            type="button"
+            variant={isSelected ? "PrimeStyle" : "BorderStyle"}
+            size="S"
+            onClick={() => onSelect(format)}
+            className="uppercase"
+          >
+            {format}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+This gives you:
+
+- Auto-sizing horizontal padding via the button's `px-*` defaults
+- Theme-correct surface and text tokens (button variants are pre-themed)
+- Clear pressed/unpressed visual via `PrimeStyle` (filled) vs `BorderStyle` (outlined)
+- All the focus/disabled/loading states from `Button` for free
+
+### When `Toggle` IS the right component
+
+Reserve `Toggle` for its actual designed use case — **icon-only toolbar actions** with a binary on/off state:
+
+- Bold / Italic / Underline in a rich-text toolbar
+- Play / Pause
+- Grid / List view
+- Mute / Unmute
+- Eye / Eye-slash (show/hide password)
+
+```tsx
+<Toggle pressed={isBold} onPressedChange={setBold} aria-label="Bold">
+  <i className="ri-bold" />
+</Toggle>
+```
+
+The icon must fit within the square dimension — `[&_i]:text-[14px]` for size M, etc.
+
 ## Common Patterns
 
 ### Toolbar Group

package/docs/llms-manifest.json

@@ -64,7 +64,7 @@
         { "name": "Card", "version": "1.1.15", "documented": false },
         { "name": "CNLayout", "version": "1.1.15", "documented": false },
         { "name": "FieldSection", "version": "1.1.15", "documented": false },
-        { "name": "SectionCard", "version": "1.1.22", "documented": true },
+        { "name": "SectionBlock", "version": "1.1.22", "documented": true },
         { "name": "TreeSubLayout", "version": "1.1.15", "documented": false },
         { "name": "Divider", "version": "1.1.15", "documented": false },
         { "name": "ScrollArea", "version": "1.1.15", "documented": false }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare-mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "MCP server for TORCH Glare component library — gives AI assistants full access to component docs, API references, code examples, and design system info",
   "type": "module",
   "main": "dist/index.js",