@kalink-ui/seedly 0.34.4 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @kalink-ui/seedly
 
+## 0.35.0
+
+### Minor Changes
+
+- e06ff34: Add responsive typography generation and wire it into text-bearing components.
+- 63a0911: Align theming and responsive APIs across components with shared tone helpers.
+
+### Patch Changes
+
+- 89cc8dc: Add a responsive argType helper and refine typography story controls.
+- eae06e2: Align surface and tone token usage with the updated theme contract.
+
 ## 0.34.4
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,34 @@
+# `seedly`
+
+Seedly is a React UI component library powered by vanilla-extract and the Kalink UI design system.
+
+## Install
+
+```bash
+pnpm add @kalink-ui/seedly
+```
+
+## Next.js setup
+
+Seedly ships TypeScript and vanilla-extract sources, so Next.js must transpile the package.
+
+```ts
+// next.config.ts
+import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';
+
+const withVanillaExtract = createVanillaExtractPlugin();
+
+const nextConfig = {
+  transpilePackages: ['@kalink-ui/seedly'],
+};
+
+export default withVanillaExtract(nextConfig);
+```
+
+Import Seedly layers and your system theme once in `app/layout.tsx`:
+
+```ts
+import '@kalink-ui/seedly/styles/reset';
+import '@kalink-ui/seedly/styles/layers';
+import '../style/system-theme.css';
+```

package/docs/component-theming.md

@@ -0,0 +1,295 @@
+# Component theming contract (internal)
+
+This document defines the **target standard** for Seedly component theming. It is
+intended for internal implementation guidance and will later be adapted for
+external documentation.
+
+## Principles
+
+- **Vanilla Extract is mandatory**. Components must expose theming hooks as VE
+  contracts, not runtime styles or plain CSS.
+- **Semantic naming over CSS naming**. Use neutral, role-based semantics so the
+  API describes intent instead of implementation details.
+- **Structure and appearance are both tokenized**. Spacing, typography, shape,
+  elevation, motion, and color/border/shadow must map to `sys` tokens and
+  component vars.
+- **Vars are the primary override surface**. Variants should only mutate vars,
+  not hard-code raw values.
+- **Slots are opt-in escape hatches**. Export slot classes when components have
+  internal structure.
+- **System tokens are the base**. Default component vars must map to `sys` tokens
+  (or other component vars) before any literals.
+
+## Contract naming rules
+
+### Structure vs appearance
+
+Structure (spacing, typography, shape, elevation, motion, layout) and appearance
+(color, borders, shadows, emphasis) are **organizational categories only**. Both
+must be expressed through system tokens and component vars so they are fully
+overridable.
+
+### System tokens
+
+System tokens live in `sys` and are **semantic**: `sys.surface.background`,
+`sys.state.hovered.opacity`, `sys.shape.corner.rounded`.
+
+### Component contracts
+
+Component contracts (`ComponentVars`) must stay semantic and scoped to the
+component. Favor neutral, role-based terminology:
+
+- `color.container` (surface background)
+- `color.content` (text/icon color)
+- `color.outline` (borders, focus ring)
+- `shape.corner` (border radius)
+- `elevation.level` (shadow)
+- `spacing.inline` / `spacing.block` (layout spacing)
+- `typography.kind` (font or style anchor if needed)
+
+CSS-names are only allowed for leaf-level spacing/size values where the intent is
+unambiguous.
+
+## Variants
+
+Variants are semantic and should only **assign vars**.
+
+### Variant naming
+
+- Preferred: `filled`, `outlined`, `text`, `elevated`, `tonal`.
+- Allowed alternates: `ghost`, `plain`, `link` if a component requires them.
+- Avoid: `primary`, `secondary` (these are **tones**, not visual treatments).
+
+### Variant rules
+
+- Variants set component vars via `assignVars` for both structure and appearance.
+- Variants should not set hard-coded CSS values except for layout primitives
+  (e.g., `display`, `gap`), and only when those are not intended for theming.
+
+## Size and density
+
+Size and density are separate axes:
+
+- **Size** controls typography scale and overall component scale.
+- **Density** controls padding and spacing.
+
+### Naming
+
+- **Size**: `sm`, `md`, `lg` (universal).
+- **Density**: `compact`, `comfortable`, `spacious` (use only when necessary).
+
+### Rules
+
+- Size variants should assign typography and scale-related vars.
+- Density variants should only assign spacing vars.
+- Components can implement size only if density is not relevant.
+
+## Export surface
+
+Every component must export the following, when applicable:
+
+- `ComponentVars` contract (e.g. `buttonVars`).
+- `componentRecipe` and `ComponentVariants` type.
+- Slot classes (e.g. `buttonLabel`, `buttonSlot`) for structured components.
+- Optional variant maps (`componentVariantStyles`, `componentSizeStyles`) when
+  responsive recipes or overrides are needed.
+
+## Canonical component template
+
+```ts
+import { assignVars, createThemeContract } from '@vanilla-extract/css';
+import { recipe, type RecipeVariants } from '@vanilla-extract/recipes';
+
+import { sys } from '../../styles';
+import { components } from '../../styles/layers.css';
+
+export const componentVars = createThemeContract({
+  color: {
+    container: null,
+    content: null,
+    outline: null,
+  },
+  spacing: {
+    block: null,
+    inline: null,
+  },
+  shape: {
+    corner: null,
+  },
+  typography: {
+    size: null,
+    weight: null,
+    lineHeight: null,
+  },
+});
+
+export const componentVariantStyles = {
+  filled: {
+    '@layer': {
+      [components]: {
+        vars: {
+          ...assignVars(componentVars.color, {
+            container: sys.surface.foreground,
+            content: sys.surface.background,
+            outline: 'transparent',
+          }),
+        },
+      },
+    },
+  },
+  outlined: {
+    '@layer': {
+      [components]: {
+        vars: {
+          ...assignVars(componentVars.color, {
+            container: 'transparent',
+            content: sys.surface.foreground,
+            outline: sys.surface.foreground,
+          }),
+        },
+      },
+    },
+  },
+} as const;
+
+export const componentSizeStyles = {
+  sm: {
+    '@layer': {
+      [components]: {
+        vars: assignVars(componentVars.spacing, {
+          block: sys.spacing[1],
+          inline: sys.spacing[2],
+        }),
+      },
+    },
+  },
+  md: {
+    '@layer': {
+      [components]: {
+        vars: assignVars(componentVars.spacing, {
+          block: sys.spacing[2],
+          inline: sys.spacing[4],
+        }),
+      },
+    },
+  },
+  lg: {
+    '@layer': {
+      [components]: {
+        vars: assignVars(componentVars.spacing, {
+          block: sys.spacing[3],
+          inline: sys.spacing[6],
+        }),
+      },
+    },
+  },
+} as const;
+
+export const componentRecipe = recipe({
+  base: {
+    '@layer': {
+      [components]: {
+        color: componentVars.color.content,
+        backgroundColor: componentVars.color.container,
+        borderColor: componentVars.color.outline,
+        borderRadius: componentVars.shape.corner,
+        paddingBlock: componentVars.spacing.block,
+        paddingInline: componentVars.spacing.inline,
+        fontSize: componentVars.typography.size,
+        fontWeight: componentVars.typography.weight,
+        lineHeight: componentVars.typography.lineHeight,
+
+        vars: {
+          ...assignVars(componentVars.color, {
+            container: sys.surface.background,
+            content: sys.surface.foreground,
+            outline: 'transparent',
+          }),
+          ...assignVars(componentVars.spacing, {
+            block: sys.spacing[2],
+            inline: sys.spacing[4],
+          }),
+          ...assignVars(componentVars.shape, {
+            corner: sys.shape.corner.none,
+          }),
+          ...assignVars(componentVars.typography, {
+            size: sys.typography.body.medium.size,
+            weight: sys.typography.body.medium.weight,
+            lineHeight: sys.typography.body.medium.lineHeight,
+          }),
+        },
+      },
+    },
+  },
+  variants: {
+    variant: componentVariantStyles,
+    size: componentSizeStyles,
+  },
+  defaultVariants: {
+    variant: 'filled',
+    size: 'md',
+  },
+});
+
+export type ComponentVariants = NonNullable<
+  RecipeVariants<typeof componentRecipe>
+>;
+```
+
+## Component example: Button
+
+### Contract
+
+Use semantic keys and map to system tokens by default:
+
+- `buttonVars.color.container` → `sys.surface.foreground`
+- `buttonVars.color.content` → `sys.surface.background`
+- `buttonVars.color.outline` → `sys.surface.foreground`
+- `buttonVars.spacing.block` / `inline` → `sys.spacing`
+- `buttonVars.shape.corner` → `sys.shape.corner`
+- `buttonVars.elevation.level` → `sys.elevation`
+
+### Variant strategy
+
+- `filled`: container + content set via vars.
+- `outlined`: outline set, container transparent.
+- `text`: container transparent, no outline, hover uses state tokens.
+
+### Size strategy
+
+- `sm/md/lg` adjust typography + spacing vars.
+- If density is introduced, keep size tied to typography and use density to
+  adjust spacing only.
+
+## Consumer override example
+
+```ts
+import { assignVars } from '@vanilla-extract/css';
+import { buttonVars } from '@kalink-ui/seedly/button';
+
+export const marketingButton = style({
+  vars: assignVars(buttonVars, {
+    color: {
+      container: '#111',
+      content: '#fff',
+      outline: '#111',
+    },
+    spacing: {
+      block: '10px',
+      inline: '20px',
+    },
+    shape: {
+      corner: '9999px',
+    },
+  }),
+});
+```
+
+## Notes
+
+- If a component does not need variants or slots, omit them. Do not add empty
+  contracts or classes.
+- If a component needs a tone system, model it as **data** (`tone` variant), but
+  keep visual treatment in `variant` (`filled/outlined/text`).
+- Structural overrides (spacing, typography, shape, elevation, motion) should be
+  expressed through vars, not hard-coded values.

package/docs/theming-strategy.md

@@ -0,0 +1,69 @@
+# Seedly theming strategy (internal)
+
+This document explains Seedly’s **theming philosophy** and the intended balance
+between being “unstyled” and still offering strong, composable primitives.
+
+## Goal
+
+Seedly aims to be **opinionated on functionality** but **neutral on appearance**.
+Components should be usable out-of-the-box, while giving consumers complete
+control of styling through Vanilla Extract contracts.
+
+## Core principles
+
+### 1) Separate structure from appearance
+
+- **Structure** = layout, DOM shape, spacing relationships, focus handling, and
+  accessibility.
+- **Appearance** = color, borders, radius, shadows, typography, and decorative
+  effects.
+
+**Rule:** both structure and appearance must be expressed through system tokens
+and component vars so they are fully overridable. The separation is
+organizational, not technical.
+
+### 2) System tokens are semantic and minimal
+
+- `sys` represents **semantic roles**, not palettes.
+- Roles must stay neutral so Seedly is not locked to any single design language.
+- Consumers map their `refs` layer into `sys.surface`, `sys.tone`, and other
+  system roles in userland.
+
+### 3) Component contracts carry the styling surface
+
+- `ComponentVars` are the primary styling API.
+- Variants should **assign vars**, not hard-code raw values.
+- Slots are opt-in escape hatches for structured components.
+
+### 4) Optional presets, never mandatory
+
+Seedly can ship a **reference theme** as an optional layer. It must live
+separately from contracts so consumers can ignore or replace it.
+
+## What “unstyled” means in Seedly
+
+Seedly is **unstyled in appearance**, not in structure. Components should:
+
+- Provide accessible structure and layout.
+- Avoid locking consumers into a specific visual language.
+- Still render with a usable default look when paired with a reference theme.
+
+## Expected consumer workflow
+
+1. Define palette (`refs`) and map it to semantic roles (`sys`).
+2. Optionally apply a reference theme for quick setup.
+3. Override per-component vars when deeper customization is required.
+
+## Non-goals
+
+- Runtime theming is not a priority.
+- CSS-only overrides are not a primary target.
+- Seedly should not encode a full external design spec in its system contract.
+
+## Summary
+
+Seedly stays in the middle by:
+
+- Keeping system roles **semantic and minimal**.
+- Exposing **component-level contracts** as the main styling surface.
+- Allowing **optional presets** for convenience without locking consumers in.

package/docs/tone-system.md

@@ -0,0 +1,139 @@
+# Tone system (internal)
+
+This document defines the **tone system** for Seedly's semantic color
+architecture. It is intended for internal implementation guidance and will later
+be adapted for external documentation.
+
+## Overview
+
+Seedly separates colors into two distinct concerns:
+
+1. **Surface colors** (`sys.surface`) — The page-level canvas
+2. **Tone colors** (`sys.tone`) — Semantic colors for interactive and stateful
+   elements
+
+Surface expresses the neutral canvas of the application, so components can
+anchor their defaults against a consistent base layer before applying tones for
+emphasis.
+
+This separation exists because a neutral interactive element sitting on a page
+is visually distinct from the page background itself. Keeping them separate
+gives consumers full control over both layers.
+
+## Surface colors
+
+Surface colors define the default page/app appearance:
+
+| Token                    | Purpose                          |
+| ------------------------ | -------------------------------- |
+| `sys.surface.background` | Page or app background           |
+| `sys.surface.foreground` | Default text color on background |
+
+These tokens are the canvas on which components are rendered. They can also
+serve as a neutral foundation for components that should blend with the base
+surface before tones are applied.
+
+## Tone colors
+
+Tones are semantic color pairs for interactive elements and stateful feedback.
+Each tone consists of two tokens following the `on{Name}` convention:
+
+| Pattern             | Purpose                                    |
+| ------------------- | ------------------------------------------ |
+| `sys.tone.{name}`   | The tone's base color (container/surface)  |
+| `sys.tone.on{Name}` | The contrasting color (content/text on it) |
+
+### Defined tones
+
+| Tone          | Purpose                                        |
+| ------------- | ---------------------------------------------- |
+| `neutral`     | Default interactive elements without emphasis  |
+| `primary`     | Brand emphasis, main calls-to-action           |
+| `destructive` | Errors, dangerous/irreversible actions         |
+| `success`     | Positive feedback, confirmations, valid states |
+
+## Why separate surface from tones?
+
+A neutral button needs to stand out from the page surface. If they shared the
+same token, you could not style a neutral button differently from the page
+background.
+
+Keeping them separate allows:
+
+- Neutral elements to be visually distinct from the surface
+- Surface to change independently of component tones
+- Consumers to alias them if their design requires it
+
+## Component integration
+
+Components use `tone` as a variant axis to apply semantic colors. The `variant`
+axis controls visual treatment (filled, outlined, text). These are orthogonal
+concerns.
+
+### Variant and tone interaction
+
+The `variant` controls how tones are applied:
+
+| Variant    | Container         | Content             | Outline           |
+| ---------- | ----------------- | ------------------- | ----------------- |
+| `filled`   | `sys.tone.{tone}` | `sys.tone.on{Tone}` | `transparent`     |
+| `outlined` | `transparent`     | `sys.tone.{tone}`   | `sys.tone.{tone}` |
+| `text`     | `transparent`     | `sys.tone.{tone}`   | `transparent`     |
+
+Component vars (e.g. `buttonVars.color.outline`) map to tone tokens when a tone
+is active, but can be overridden independently at the component level.
+
+### State modifiers
+
+Tones rely on global state tokens for hover, pressed, and disabled styling:
+
+- `sys.state.hovered.opacity`
+- `sys.state.pressed.opacity`
+- `sys.state.muted.light`
+- `sys.state.muted.dark`
+
+Disabled states should reduce contrast using the muted tokens, regardless of the
+active tone.
+
+### Form field error states
+
+Form components use the `destructive` tone for error states and the `success`
+tone for valid states. This is applied via data attributes or internal state,
+not as a variant.
+
+## Design decisions
+
+### Why not expand `sys.surface` with semantic slots?
+
+The theming strategy states that Seedly should not encode a full external design
+spec in its system contract. Adding `primary`, `destructive`, etc. directly to
+`sys.surface` would mix surface concerns with interactive semantics. The
+`sys.tone` namespace keeps them organized and purpose-clear.
+
+### Why flat tokens instead of nested?
+
+Flat structure (`sys.tone.primary`, `sys.tone.onPrimary`) instead of nested
+(`sys.tone.primary.base`, `sys.tone.primary.onBase`) because:
+
+- Shorter paths in component code
+- Matches established design system conventions
+- Simpler mental model
+
+### Why these four tones?
+
+| Tone          | Justification                                      |
+| ------------- | -------------------------------------------------- |
+| `neutral`     | Every design system needs a default                |
+| `primary`     | Brand emphasis is universal                        |
+| `destructive` | Error states and dangerous actions are unavoidable |
+| `success`     | Form validation requires both error and success    |
+
+Additional tones can be added later if needed, but these four cover the
+essential use cases without over-specifying a design language.
+
+## Summary
+
+- `sys.surface` defines the page-level surface (background/foreground)
+- `sys.tone` defines semantic interactive colors
+- Components expose `tone` as a variant axis alongside `variant` and `size`
+- Tones use flat pairs: `{tone}` and `on{Tone}`

package/docs/value-and-scope.md

@@ -0,0 +1,65 @@
+# Seedly value and scope (internal)
+
+This document explains **why Seedly exists**, what it is good at, and what it
+intentionally does not try to solve.
+
+## Value statement
+
+Seedly exists to make **consistent, accessible, themeable UI** sustainable at
+scale. It provides composable primitives with a clear styling surface so teams
+can move fast without drifting into bespoke, inconsistent patterns.
+
+Seedly is not about speed to the first UI. It is about **speed to maintainable
+UI**.
+
+## Strengths
+
+- **Consistency at scale**: shared primitives reduce design drift across teams.
+- **Token-driven theming**: system roles + component contracts enable
+  multi-brand or multi-product theming without rewriting markup.
+- **Accessible behavior**: wrapping headless primitives (e.g. Radix) provides
+  robust interaction patterns out of the box.
+- **Composable API**: slots, variants, and responsive patterns create predictable
+  integration points.
+- **Build-time styling**: Vanilla Extract produces static CSS with type-safe
+  contracts.
+
+## Shortcomings and trade-offs
+
+- **Slower iteration** than Tailwind-first or LLM-generated UI for one-off
+  screens.
+- **Higher onboarding cost**: consumers must learn tokens, contracts, and VE.
+- **Less suited to bespoke design**: one-off visual treatments require more work.
+- **Wrapper maintenance**: upstream headless changes must be tracked carefully.
+- **Not optimized for runtime theming**: compile-time theming is the default.
+
+## Scope boundaries
+
+Seedly focuses on **functional primitives** with a robust styling surface. It is
+not a full design system or a complete UI kit.
+
+### In scope
+
+- Accessible, composable primitives with stable APIs.
+- System roles and component contracts for structure and appearance.
+- Variant, size, tone, and responsive patterns.
+- Optional reference themes for bootstrapping.
+
+### Out of scope
+
+- A prescriptive visual design language.
+- Rapid prototyping or ad-hoc UI generation.
+- Runtime theming as a first-class feature.
+- App-specific layouts or product-level design patterns.
+
+## When to use Seedly
+
+- You need **consistency across teams** or products.
+- You expect **theme reuse** or multi-brand support.
+- You value **maintainable, accessible UI** over quick, bespoke styling.
+
+## When not to use Seedly
+
+- You prioritize **iteration speed** over long-term consistency.
+- Your UI is **highly bespoke** and unlikely to be reused.
+- You are building a one-off prototype or marketing site.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalink-ui/seedly",
-  "version": "0.34.4",
+  "version": "0.35.0",
   "description": "A set of components for building UIs with React and TypeScript",
   "sideEffects": [
     "**/*.css.ts"
@@ -85,8 +85,9 @@
     "lint:fix": "pnpm lint --fix",
     "build-storybook": "storybook build",
     "dev": "storybook dev -p 6006 --no-open",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --project=unit",
+    "test:watch": "vitest --project=unit",
+    "test-storybook": "vitest run --project=storybook",
     "tsc": "tsc -b"
   }
 }

package/src/components/alert-dialog/alert-dialog-action.tsx

@@ -9,9 +9,7 @@ export type AlertDialogActionProps = ComponentPropsWithRef<typeof Action> &
   };
 
 export function AlertDialogAction({
-  className,
   children,
-  loading,
   ...props
 }: AlertDialogActionProps) {
   return (

package/src/components/alert-dialog/alert-dialog-cancel.tsx

@@ -7,7 +7,6 @@ export type AlertDialogCancelProps = ComponentPropsWithRef<typeof Cancel> &
   ButtonProps<'button'>;
 
 export function AlertDialogCancel({
-  className,
   children,
   ...props
 }: AlertDialogCancelProps) {

package/src/components/alert-dialog/alert-dialog-content.css.ts

@@ -26,7 +26,7 @@ const exitAnimation = keyframes({
   },
 });
 
-export const alertDialogContent = recipe({
+export const alertDialogContentRecipe = recipe({
   base: {
     '@layer': {
       [components]: {