+
+
+### Size
+
+`medium` (default) suits most inline uses; step up to `large` for emphasis, down to `small` for
+dense layouts. The text size scales with the badge (12 / 14 / 18 px).
+
+small
+medium
+large`}
+>
+
` wrapping the `children` in a `Typography` ``.
+
+## API Reference
+
+Renders a `
` and forwards its `ref`.
+
+| Prop | Type | Default | Description |
+| ---------- | ------------------------------------- | ---------- | ------------------------------------ |
+| `children` | `ReactNode` | — | The badge's content, rendered as text. |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Padding and text size. |
+| `variant` | `'filled' \| 'outline' \| 'weak'` | `'filled'` | Visual emphasis. |
+
+Also accepts every `ComponentProps<'div'>` (`className`, `onClick`, …), forwarded to the rendered
+`
`. The `
` carries `role="status"`, so screen readers announce its content as a live
+status message.
diff --git a/www/docs/components/card.mdx b/www/docs/components/card.mdx
new file mode 100644
index 00000000..b17745b5
--- /dev/null
+++ b/www/docs/components/card.mdx
@@ -0,0 +1,111 @@
+---
+sidebar_label: Card
+---
+
+import { Card } from '@sipe-team/card';
+
+# Card
+
+A container that groups related content into a surface, with a fixed aspect ratio.
+
+## Installation
+
+```sh
+npm install @sipe-team/card
+```
+
+```ts
+import '@sipe-team/card/styles.css';
+```
+
+## Usage
+
+Give the card a width; its height follows from the `ratio`. Content is centered inside it.
+
+Card`}
+>
+ Card
+
+
+## Examples
+
+### Variant
+
+`filled` (default) sits on a subtle background with a soft border; `outline` uses the default
+background with a stronger border; `ghost` is transparent with no border or padding.
+
+filled
+outline
+ghost`}
+>
+
+ filled
+ outline
+ ghost
+
+
+
+### Ratio
+
+The card's height is derived from its width via `aspect-ratio`. `rectangle` (default) is 16:9;
+`square` is 1:1; `wide` is 21:9; `portrait` is 3:4; `auto` lets the content size the height.
+
+16:9
+1:1
+21:9
+3:4
+auto`}
+>
+
+ 16:9
+ 1:1
+ 21:9
+ 3:4
+ auto
+
+
+
+### `asChild`
+
+Drops the wrapping `div` and merges the card's styling onto the element it renders, so the card
+becomes a single element — here, an ``.
+
+
+ Link card
+`}
+>
+
+ Link card
+
+
+
+## Anatomy
+
+```tsx
+import { Card } from '@sipe-team/card';
+
+export default () => (
+
+ Content
+
+);
+```
+
+Renders a single `
` that centers its `children`.
+
+## API Reference
+
+Renders a `
` (or the child element when `asChild` is set) and forwards its `ref`.
+
+| Prop | Type | Default | Description |
+| ---------- | ------------------------------------------------------------- | ------------- | -------------------------------------------------------- |
+| `variant` | `'filled' \| 'outline' \| 'ghost'` | `'filled'` | Surface style — background, border, and padding. |
+| `ratio` | `'rectangle' \| 'square' \| 'wide' \| 'portrait' \| 'auto'` | `'rectangle'` | `aspect-ratio` used to derive height from width. |
+| `asChild` | `boolean` | `false` | Merge props onto the child instead of rendering a `div`. |
+
+Also accepts every `ComponentProps<'div'>` (`className`, `style`, `onClick`, …), forwarded to the
+rendered element. The element carries `role="presentation"`.
diff --git a/www/docs/components/chip.mdx b/www/docs/components/chip.mdx
new file mode 100644
index 00000000..9f7cb0c2
--- /dev/null
+++ b/www/docs/components/chip.mdx
@@ -0,0 +1,212 @@
+---
+sidebar_label: Chip
+---
+
+import { useState } from 'react';
+import { Chip } from '@sipe-team/chip';
+
+{/* Chip hardcodes light-surface colors (e.g. outline text is `gray700`), so it needs a light backdrop
+ to be legible on the dark-only docs stage. This wrapper is presentational only and is intentionally
+ left out of the `code` strings below. */}
+export const LightStage = ({ children }) => (
+
`}
+>
+
+
+
+
+
+### Disabled
+
+The native `disabled` attribute is forwarded to the `
`}
+>
+
+ Left
+
+ Right
+
+
+
+### Color
+
+`default` is a subtle gray; `primary` uses the brand cyan; `dark` is a strong near-black.
+
+Because `dark` is near-black, it is intended for light surfaces — on a dark background it blends
+in. The panel below is kept light so all three colors stay visible regardless of the page theme.
+
+
+
+`}
+>
+
+
+
+
+
+
+
+## Anatomy
+
+```tsx
+import { Divider } from '@sipe-team/divider';
+
+export default () => ;
+```
+
+Renders a single `` with `aria-orientation` set to match `orientation`.
+
+## API Reference
+
+Renders an `` and forwards its `ref`.
+
+| Prop | Type | Default | Description |
+| ------------- | ----------------------------- | -------------- | ---------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Line direction. `horizontal` is full-width; `vertical` is full-height. |
+| `color` | `'default' \| 'primary' \| 'dark'` | `'default'` | Line color. |
+
+Also accepts every `ComponentProps<'hr'>` (`className`, `style`, …), forwarded to the ``.
+Override `style` for custom thickness, dashes, or color.
diff --git a/www/docs/components/flex.mdx b/www/docs/components/flex.mdx
new file mode 100644
index 00000000..d6e27b07
--- /dev/null
+++ b/www/docs/components/flex.mdx
@@ -0,0 +1,273 @@
+---
+sidebar_label: Flex
+---
+
+import { Flex } from '@sipe-team/flex';
+
+{/* Flex's layout demos need visible blocks to show alignment/spacing; this placeholder box is
+ presentational only and is intentionally left out of the `code` strings below. */}
+export const Box = ({ children, style }) => (
+
+ {children}
+
+);
+
+# Flex
+
+A `
` (or polymorphic element) that lays out its children with CSS flexbox, with per-breakpoint
+responsive values for `direction`, `align`, `justify`, `wrap`, and `gap`.
+
+## Installation
+
+```sh
+npm install @sipe-team/flex
+```
+
+```ts
+import '@sipe-team/flex/styles.css';
+```
+
+## Usage
+
+Flex defaults to `direction="row"` with `nowrap`. Give it a `gap` to space children out.
+
+
+ 1
+ 2
+ 3
+`}
+>
+
+ 1
+ 2
+ 3
+
+
+
+## Examples
+
+### Direction
+
+`row` (default), `column`, `row-reverse`, `column-reverse` — maps to `flex-direction`.
+
+123
+123
+123`}
+>
+
+ 123
+ 123
+ 123
+
+
+
+### Align
+
+`align` maps to `align-items`. Items below have different heights to make the effect visible.
+
+
+ A
+ B
+ C
+`}
+>
+
+ A
+ B
+ C
+
+
+
+### Justify
+
+`justify` maps to `justify-content`.
+
+
+ 1
+ 2
+ 3
+`}
+>
+
+ 1
+ 2
+ 3
+
+
+
+### Wrap
+
+`wrap` maps to `flex-wrap`; constrain the container's width to see items wrap onto new lines.
+
+
+ 1
+ 2
+ 3
+`}
+>
+
+ 1
+ 2
+ 3
+
+
+
+### Item sizing — `basis`, `grow`, `shrink`
+
+`basis`, `grow`, and `shrink` apply to the `Flex` element itself (not to its children) — use them
+when a `Flex` is nested as an item inside a parent flex container.
+
+
+ fixed 80px
+ grow 1
+ grow 2
+`}
+>
+
+ fixed 80px
+ grow 1
+ grow 2
+
+
+
+### Inline
+
+`inline` switches `display` from `flex` to `inline-flex`, so the container sits inline with
+surrounding text instead of taking a full line.
+
+
+ Text before
+
+ 1
+ 2
+
+ text after
+`}
+>
+
+ Text before
+
+ 1
+ 2
+
+ text after
+
+
+
+### Responsive values
+
+`direction`, `align`, `justify`, `wrap`, and `gap` each accept either a single value or an object
+keyed by breakpoint — `sm` (the default, no media query), `md` (`min-width: 780px`), `lg`
+(`min-width: 1060px`). Each breakpoint falls back to the previous one when omitted, so only the
+values that change need to be set. Resize the browser past 780px/1060px to see this example switch
+from a stacked column to a row.
+
+
+ 1
+ 2
+ 3
+`}
+>
+
+ 1
+ 2
+ 3
+
+
+
+### `asChild`
+
+Drops the wrapping `
` and merges the flex layout onto the element you provide.
+
+
+
+`}
+>
+
+
+
+
+
+## Anatomy
+
+```tsx
+import { Flex } from '@sipe-team/flex';
+
+export default () => (
+
+
Item
+
Item
+
+);
+```
+
+Renders a single `
` (or the child element when `asChild` is set) and forwards its `ref`.
+
+## API Reference
+
+Renders a `
` (or the child element when `asChild` is set) and forwards its `ref` to that
+underlying element.
+
+| Prop | Type | Default | Description |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------------- |
+| `direction` | `ResponsiveValue<'row' \| 'column' \| 'row-reverse' \| 'column-reverse'>` | `'row'` | `flex-direction`. |
+| `align` | `ResponsiveValue<'flex-start' \| 'flex-end' \| 'center' \| 'stretch' \| 'baseline' \| 'normal'>` | `'normal'` | `align-items`. |
+| `justify` | `ResponsiveValue<'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly' \| 'normal'>` | `'normal'` | `justify-content`. |
+| `wrap` | `ResponsiveValue<'nowrap' \| 'wrap' \| 'wrap-reverse'>` | `'nowrap'` | `flex-wrap`. |
+| `gap` | `ResponsiveValue` | — | Gap between items. Accepts any CSS `gap` value or a number (px). |
+| `basis` | `CSSProperties['flexBasis']` | — | `flex-basis` of the `Flex` element itself, as an item in its own parent. |
+| `grow` | `CSSProperties['flexGrow']` | — | `flex-grow` of the `Flex` element itself. |
+| `shrink` | `CSSProperties['flexShrink']` | — | `flex-shrink` of the `Flex` element itself. |
+| `inline` | `boolean` | `false` | Uses `inline-flex` instead of `flex`. |
+| `asChild` | `boolean` | `false` | Merge props onto the child instead of rendering a `div`. |
+
+`ResponsiveValue` is `T | Partial>`, exported from
+`@sipe-team/flex` along with `FlexBreakpoint` (`'sm' | 'md' | 'lg'`).
+
+Also accepts every `ComponentProps<'div'>` (`className`, `style`, `onClick`, …), forwarded to the
+rendered element. `style` is merged after the computed layout styles, so it can override them.
+
+## Known limitations
+
+- The `md`/`lg` breakpoints (`780px`/`1060px`) are hardcoded locally rather than sourced from
+ `@sipe-team/tokens` — the token package's layout breakpoints are deprecated, and `Flex` keeps
+ these values in place until replacement tokens ship. They may change in a future version.
+- Only `direction`, `align`, `justify`, `wrap`, and `gap` are responsive. `basis`, `grow`, `shrink`,
+ and `inline` apply the same value at every breakpoint.
diff --git a/www/docs/components/grid.mdx b/www/docs/components/grid.mdx
new file mode 100644
index 00000000..df9eede5
--- /dev/null
+++ b/www/docs/components/grid.mdx
@@ -0,0 +1,258 @@
+---
+sidebar_label: Grid
+---
+
+import { Grid, GridItem } from '@sipe-team/grid';
+
+{/* Grid's layout demos need visible blocks to show placement; this placeholder box is presentational
+ only and is intentionally left out of the `code` strings below. */}
+export const Box = ({ children, style }) => (
+
+ {children}
+
+);
+
+# Grid
+
+A `
` that lays out its children with CSS grid, plus a `GridItem` for per-item placement
+(column/row span or start/end, named areas, and self-alignment).
+
+## Installation
+
+```sh
+npm install @sipe-team/grid
+```
+
+```ts
+import '@sipe-team/grid/styles.css';
+```
+
+## Usage
+
+Give `Grid` a `templateColumns` and `gap`; children fill the implicit grid in source order.
+
+
+ 1
+ 2
+ 3
+`}
+>
+
+ 1
+ 2
+ 3
+
+
+
+## Examples
+
+### Named areas
+
+`templateAreas` names regions of the grid; each `GridItem` claims one with a matching `area`.
+
+
+ Header
+ Sidebar
+ Main
+ Footer
+`}
+>
+
+ Header
+ Sidebar
+ Main
+ Footer
+
+
+
+### Spanning columns and rows
+
+`colSpan`/`rowSpan` are shorthand for `grid-column`/`grid-row: span N`.
+
+
+ rowSpan 2
+ colSpan 2
+ colSpan 1
+ colSpan 3
+`}
+>
+
+ rowSpan 2
+ colSpan 2
+ colSpan 1
+ colSpan 3
+
+
+
+### Explicit start/end
+
+`colStart`/`colEnd` and `rowStart`/`rowEnd` build a `start / end` line range (each defaults to
+`auto`). They only take effect when `column`/`row` and `colSpan`/`rowSpan` are unset — see
+[GridItem](#griditem) for the full priority order.
+
+
+ col 2 → 4
+`}
+>
+
+ col 2 → 4
+
+
+
+### Item self-alignment
+
+`justifySelf`/`alignSelf` on a `GridItem` position it within its own cell.
+
+
+ start
+ center
+ end
+`}
+>
+
+ start
+ center
+ end
+
+
+
+### Nested grids
+
+`Grid` nests freely — an inner `Grid` lays out independently of its parent.
+
+
+ Outer
+
+ Inner 1
+ Inner 2
+
+`}
+>
+
+ Outer
+
+ Inner 1
+ Inner 2
+
+
+
+
+### `asChild`
+
+Both `Grid` and `GridItem` support `asChild` to drop their wrapping `
` and merge onto the
+element you provide.
+
+
+
+ 1
+ 2
+
+`}
+>
+
+
+ 1
+ 2
+
+
+
+
+## Anatomy
+
+```tsx
+import { Grid, GridItem } from '@sipe-team/grid';
+
+export default () => (
+
+ Item
+ Item
+
+);
+```
+
+`Grid` renders a single `
` (or the child element when `asChild` is set). `GridItem` is not
+required — any element works as a grid child — it only adds per-item placement props.
+`@sipe-team/grid` also exports `Root` and `Item` as aliases for `Grid` and `GridItem`, for a
+``/`` compound-component import style (`import * as Grid from '@sipe-team/grid'`).
+
+## API Reference
+
+### `Grid`
+
+Renders a `
` (or the child element when `asChild` is set) and forwards its `ref`.
+
+| Prop | Type | Default | Description |
+| ----------------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `templateColumns` | `CSSProperties['gridTemplateColumns']` | — | `grid-template-columns`. |
+| `templateRows` | `CSSProperties['gridTemplateRows']` | — | `grid-template-rows`. |
+| `templateAreas` | `CSSProperties['gridTemplateAreas']` | — | `grid-template-areas`. |
+| `gap` | `CSSProperties['gap']` | `'0'` | `gap`. |
+| `autoFlow` | `CSSProperties['gridAutoFlow']` | `'row'` | `grid-auto-flow`. |
+| `inline` | `boolean` | `false` | Uses `inline-grid` instead of `grid`. |
+| `asChild` | `boolean` | `false` | Merge props onto the child instead of rendering a `div`. |
+
+Also accepts every `ComponentProps<'div'>` (`className`, `style`, `onClick`, …), forwarded to the
+rendered element. `Grid` also declares `autoRows`/`autoColumns` props
+(`CSSProperties['gridAutoRows']`/`CSSProperties['gridAutoColumns']`), but see
+[Known limitations](#known-limitations) — they currently have no visual effect.
+
+### `GridItem`
+
+Renders a `
` (or the child element when `asChild` is set) and forwards its `ref`.
+
+| Prop | Type | Default | Description |
+| ------------- | --------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `column` | `CSSProperties['gridColumn']` | — | `grid-column`. Takes priority over `colSpan` and `colStart`/`colEnd`. |
+| `row` | `CSSProperties['gridRow']` | — | `grid-row`. Takes priority over `rowSpan` and `rowStart`/`rowEnd`. |
+| `area` | `CSSProperties['gridArea']` | — | `grid-area`, for placing into a named `templateAreas` region. |
+| `colSpan` | `number` | — | Shorthand for `grid-column: span N`. Used only when `column` is unset. |
+| `rowSpan` | `number` | — | Shorthand for `grid-row: span N`. Used only when `row` is unset. |
+| `colStart` | `number \| 'auto'` | — | Start line of `grid-column`. Used only when `column` and `colSpan` are unset. |
+| `colEnd` | `number \| 'auto'` | — | End line of `grid-column`. Used only when `column` and `colSpan` are unset. |
+| `rowStart` | `number \| 'auto'` | — | Start line of `grid-row`. Used only when `row` and `rowSpan` are unset. |
+| `rowEnd` | `number \| 'auto'` | — | End line of `grid-row`. Used only when `row` and `rowSpan` are unset. |
+| `justifySelf` | `CSSProperties['justifySelf']` | — | `justify-self`. |
+| `alignSelf` | `CSSProperties['alignSelf']` | — | `align-self`. |
+| `asChild` | `boolean` | `false` | Merge props onto the child instead of rendering a `div`. |
+
+Also accepts every `ComponentProps<'div'>` (`className`, `style`, `onClick`, …), forwarded to the
+rendered element.
+
+## Known limitations
+
+- `Grid`'s `autoRows` and `autoColumns` props set internal CSS custom properties, but the compiled
+ stylesheet never reads them back into `grid-auto-rows`/`grid-auto-columns` — passing either prop
+ currently has no visual effect. Use `style={{ gridAutoRows: ... }}` / `style={{ gridAutoColumns: ... }}`
+ as a workaround.
+- `Grid` has no `alignItems`/`justifyItems`/`alignContent`/`justifyContent` props for container-level
+ alignment, even though the stylesheet has unwired hooks for them internally. Use
+ `style={{ alignItems: ... }}` etc. on `Grid`, or align individual children with `GridItem`'s
+ `alignSelf`/`justifySelf`.
diff --git a/www/docs/components/icon.mdx b/www/docs/components/icon.mdx
new file mode 100644
index 00000000..e1267c03
--- /dev/null
+++ b/www/docs/components/icon.mdx
@@ -0,0 +1,237 @@
+---
+sidebar_label: Icon
+---
+
+import { useState } from 'react';
+import {
+ AccordionArrowIcon,
+ CheckCircleIcon,
+ EmailIcon,
+ GithubIcon,
+ InstagramIcon,
+ KakaoIcon,
+ LinkedinIcon,
+ LinkIcon,
+ OrganizerIcon,
+ UserIcon,
+ YoutubeIcon,
+} from '@sipe-team/icon';
+
+export const ALL_ICONS = [
+ ['AccordionArrowIcon', AccordionArrowIcon],
+ ['CheckCircleIcon', CheckCircleIcon],
+ ['EmailIcon', EmailIcon],
+ ['GithubIcon', GithubIcon],
+ ['InstagramIcon', InstagramIcon],
+ ['KakaoIcon', KakaoIcon],
+ ['LinkedinIcon', LinkedinIcon],
+ ['LinkIcon', LinkIcon],
+ ['OrganizerIcon', OrganizerIcon],
+ ['UserIcon', UserIcon],
+ ['YoutubeIcon', YoutubeIcon],
+];
+
+{/* Demonstrates the `onClick` pass-through without a native `alert()`; presentational only and left
+ out of the `code` string below. */}
+export const ClickableIcon = () => {
+ const [clicked, setClicked] = useState(false);
+ return (
+
+ );
+};
+
+# Icon
+
+A set of pre-built SVG icon components, each a `forwardRef` wrapper around fixed artwork with
+configurable `size` and `color`.
+
+## Installation
+
+```sh
+npm install @sipe-team/icon
+```
+
+Icon components render inline SVG and ship no separate stylesheet — there is no `styles.css` to
+import.
+
+## Usage
+
+Every icon is a named export. Render one directly; it defaults to 24×24.
+
+`}
+>
+
+
+
+## Examples
+
+### All icons
+
+
+ {Object.entries(icons).map(([name, Icon]) => (
+
+
+ {name}
+
+ ))}
+
`}
+>
+
+ {ALL_ICONS.map(([name, Icon]) => (
+
+
+ {name}
+
+ ))}
+
+
+
+### Size
+
+`size` sets both `width` and `height` in pixels. Default is `24`. To override `width`/`height`
+independently of `size`, pass them directly — they are spread after `size`'s and take priority.
+
+
+
+
+`}
+>
+
+
+
+
+
+
+
+
+### Color
+
+`color` sets the fill of the icon's paths. When omitted, each icon falls back to its own hardcoded
+default — see [Known limitations](#known-limitations).
+
+
+
+`}
+>
+
+
+
+
+
+
+
+### Two-tone icons
+
+`KakaoIcon` draws its badge background and face glyph as two separate paths with different default
+fill colors. Passing `color` overrides every path to the same color, which loses the two-tone look —
+compare the default (left) with a custom color (right).
+
+
+`}
+>
+
+
+
+
+
+
+### SVG props
+
+Every unlisted prop is spread onto the `