npm - @zscloud/design - Versions diffs - 0.2.0 → 0.3.0 - Mend

@zscloud/design 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/dist/components/primitive/card.d.ts +4 -1
package/dist/guidelines/Guidelines.md +28 -0
package/dist/guidelines/components/button.md +73 -0
package/dist/guidelines/components/date-picker.md +49 -0
package/dist/guidelines/components/dialog.md +93 -0
package/dist/guidelines/components/drawer.md +48 -0
package/dist/guidelines/components/form.md +100 -0
package/dist/guidelines/components/select.md +81 -0
package/dist/guidelines/components/tabs.md +73 -0
package/dist/guidelines/components/toast.md +60 -0
package/dist/guidelines/components/tooltip.md +40 -0
package/dist/guidelines/design-tokens/colors.md +74 -0
package/dist/guidelines/design-tokens/shadows.md +28 -0
package/dist/guidelines/design-tokens/spacing.md +46 -0
package/dist/guidelines/design-tokens/typography.md +62 -0
package/dist/guidelines/overview-components.md +195 -0
package/dist/guidelines/overview-icons.md +62 -0
package/dist/zscloud-design.es.js +30 -22
package/package.json +3 -2

package/dist/components/primitive/card.d.ts CHANGED Viewed

@@ -6,12 +6,15 @@ declare const cardVariants: (props?: ({
 declare const cardContentVariants: (props?: ({
     variant?: "default" | "create" | "detail" | "plain" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
+type CardVariant = "default" | "create" | "detail" | "plain" | null | undefined;
 export declare function useCardContext(): {
     isCollapsed: boolean;
     toggleCollapse: () => void;
+    variant: CardVariant;
 };
-export declare function CardProvider({ children }: {
+export declare function CardProvider({ children, variant, }: {
     children: React.ReactNode;
+    variant?: CardVariant;
 }): import("react/jsx-runtime").JSX.Element;
 export interface CardProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof cardVariants> {
 }

package/dist/guidelines/Guidelines.md ADDED Viewed

@@ -0,0 +1,28 @@
+# @zscloud/design - Design System Guidelines
+This is a React component library built on Radix UI primitives and Tailwind CSS v4. It provides 70+ production-ready components for building cloud management interfaces.
+## How to use these guidelines
+1. Always read all files whose name starts with `overview-` to understand available components and icons.
+2. When generating code for a specific component, read the corresponding file in `components/` for detailed API documentation.
+3. When applying colors, typography, spacing, or shadows, read the corresponding file in `design-tokens/`.
+## Quick start
+```tsx
+import { Button, Dialog, Select, Input } from "@zscloud/design"
+import "@zscloud/design/dist/style.css"
+```
+## Key rules
+- Always import components from `@zscloud/design`. Do not use raw HTML elements when a component exists.
+- Always import the CSS file `@zscloud/design/dist/style.css` once at the application root.
+- Use Tailwind CSS v4 utility classes for layout and custom styling. Do not write inline styles.
+- Use semantic color tokens (e.g., `text-danger-500`, `bg-theme-500`) instead of raw hex values.
+- The default control height is `h-8` (32px). Do not override unless specifically required.
+- The default border radius is `rounded-xs` (2px).
+- Spacing follows a 4px grid. Use multiples of 4px (e.g., `gap-2` = 8px, `p-4` = 16px).
+- Dark mode is supported via the `.dark` class on `<html>`. All semantic tokens automatically adapt.
+- The component library includes bilingual i18n (zh-CN / en-US). Wrap your app with `LocaleContainer` to enable translations.

package/dist/guidelines/components/button.md ADDED Viewed

@@ -0,0 +1,73 @@
+# Button
+Use for all clickable actions. Do not use raw `<button>` elements.
+## Import
+```tsx
+import { Button } from "@zscloud/design"
+```
+## Variants
+| Variant | Use for |
+|---------|---------|
+| `primary` | Main action (submit, confirm). One per section. |
+| `subtle` | Secondary actions (cancel, back) |
+| `outline` | Alternative secondary, bordered |
+| `danger` | Destructive actions (delete, remove) |
+| `ghost` | Minimal emphasis, toolbar actions |
+| `link` | Navigation-style action |
+## Sizes
+| Size | Height | Use for |
+|------|--------|---------|
+| `default` | 32px | Standard controls |
+| `sm` | 28px | Compact areas, tables |
+| `lg` | 40px | Prominent actions |
+| `icon` | 32x32px | Icon-only buttons |
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "subtle" \| "outline" \| "secondary" \| "danger" \| "ghost" \| "ghost2" \| "link"` | `"primary"` | Visual style |
+| `size` | `"default" \| "sm" \| "lg" \| "icon"` | `"default"` | Button size |
+| `icon` | `ReactNode` | - | Icon displayed before text |
+| `loading` | `boolean` | `false` | Shows spinner, disables button |
+| `disabled` | `boolean` | `false` | Disables interaction |
+| `asChild` | `boolean` | `false` | Render as child element (Slot) |
+## Examples
+```tsx
+// Primary action
+<Button>Submit</Button>
+// With icon
+<Button icon={<Icon type="add" />}>Create Resource</Button>
+// Loading state
+<Button loading>Saving...</Button>
+// Danger action
+<Button variant="danger">Delete</Button>
+// Icon-only
+<Button variant="ghost" size="icon"><Icon type="settings" /></Button>
+// Button group
+<div className="flex gap-2">
+  <Button variant="subtle">Cancel</Button>
+  <Button>Confirm</Button>
+</div>
+```
+## Rules
+- Use only one `primary` button per logical section.
+- Always pair `primary` with `subtle` for confirm/cancel patterns.
+- Use `danger` variant for destructive actions. Do not use `primary` with red styling.
+- Always show a loading state during async operations. Do not leave the button enabled.
+- Place the primary action on the right side in button groups.

package/dist/guidelines/components/date-picker.md ADDED Viewed

@@ -0,0 +1,49 @@
+# DatePicker
+Use for date and date-time selection.
+## Import
+```tsx
+import { DatePicker, RangePicker, TimePicker } from "@zscloud/design"
+```
+## Usage
+```tsx
+// Date only
+<DatePicker value={date} onChange={setDate} />
+// Date + time
+<DatePicker value={date} onChange={setDate} showTime />
+// Date range
+<RangePicker value={range} onChange={setRange} />
+// Time only
+<TimePicker value={time} onChange={setTime} />
+```
+## Props (DatePicker)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `Date \| Moment \| undefined` | - | Selected date |
+| `onChange` | `(val) => void` | - | Change handler |
+| `showTime` | `boolean` | `false` | Include time selection |
+| `showNow` | `boolean` | `true` | Show "Now" button |
+| `disabledDate` | `(date: Date) => boolean` | - | Disable specific dates |
+| `disabledTime` | `(date: Date) => DisabledTimeConfig` | - | Disable specific times |
+| `placeholder` | `string` | - | Placeholder text |
+| `format` | `string` | - | Display format |
+| `disabled` | `boolean` | `false` | Disable interaction |
+| `allowClear` | `boolean` | `true` | Show clear button |
+| `width` | `number \| string` | - | Custom width |
+## Rules
+- Use `DatePicker` for single date selection.
+- Use `RangePicker` for date range selection.
+- Use `TimePicker` for time-only selection.
+- Use `disabledDate` to prevent selecting past dates or future dates.
+- Set `showTime` only when time precision is required.

package/dist/guidelines/components/dialog.md ADDED Viewed

@@ -0,0 +1,93 @@
+# Dialog
+Use for modal interactions: confirmations, forms, and detailed content that requires focus.
+## Import
+```tsx
+import {
+  Dialog, DialogContent, DialogHeader, DialogFooter,
+  DialogTitle, DialogBody, DialogBanner, DialogScrollArea
+} from "@zscloud/design"
+```
+## Structure
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+    </DialogHeader>
+    <DialogBody>
+      {/* Content */}
+    </DialogBody>
+    <DialogFooter>
+      <Button variant="subtle" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+## Sub-components
+| Component | Purpose |
+|-----------|---------|
+| `DialogContent` | Container with overlay, animation, close button |
+| `DialogHeader` | Top section. Variants: primary, secondary |
+| `DialogTitle` | Dialog heading. Variants: normal, weak |
+| `DialogBody` | Main content area. Variants: primary, secondary |
+| `DialogFooter` | Action buttons area |
+| `DialogBanner` | Alert banner below header. Variants: danger, warning, info |
+| `DialogScrollArea` | Scrollable content area within body |
+| `DialogDivider` | Horizontal separator line |
+## Props (DialogContent)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `zIndex` | `number` | auto | Override z-index |
+| `disableAutoZIndex` | `boolean` | `false` | Disable automatic z-index |
+## Examples
+### With danger banner
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Delete Resource</DialogTitle>
+    </DialogHeader>
+    <DialogBanner variant="danger">
+      This action cannot be undone.
+    </DialogBanner>
+    <DialogBody>
+      Are you sure you want to delete this resource?
+    </DialogBody>
+    <DialogFooter>
+      <Button variant="subtle" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button variant="danger">Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+### With scrollable content
+```tsx
+<DialogBody>
+  <DialogScrollArea>
+    {/* Long content */}
+  </DialogScrollArea>
+</DialogBody>
+```
+## Rules
+- Always provide a `DialogTitle` for accessibility.
+- Always include a cancel/close mechanism.
+- Use `DialogBanner` with `variant="danger"` for destructive confirmations.
+- The z-index is managed automatically. Do not set manual z-index unless dealing with stacking issues.
+- Use `AlertDialog` instead of `Dialog` for simple confirm/cancel interactions without form content.

package/dist/guidelines/components/drawer.md ADDED Viewed

@@ -0,0 +1,48 @@
+# Drawer
+Use for side panel overlays displaying detail views, forms, or secondary content.
+## Import
+```tsx
+import { Drawer, DrawerHeader, DrawerBody, DrawerFooter } from "@zscloud/design"
+```
+## Usage
+```tsx
+<Drawer open={open} setOpen={setOpen} placement="right">
+  <DrawerHeader>Detail View</DrawerHeader>
+  <DrawerBody>
+    {/* Content */}
+  </DrawerBody>
+  <DrawerFooter>
+    <Button variant="subtle" onClick={() => setOpen(false)}>Close</Button>
+    <Button>Save</Button>
+  </DrawerFooter>
+</Drawer>
+```
+## Props (Drawer)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | required | Visibility state |
+| `setOpen` | `(open: boolean) => void` | required | State setter |
+| `placement` | `"right" \| "left" \| "top" \| "bottom"` | `"right"` | Slide direction |
+| `zIndex` | `number` | auto | Override z-index |
+## Props (DrawerHeader)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `closable` | `boolean` | `true` | Show close button |
+| `onClose` | `() => void` | - | Close handler |
+## Rules
+- Use `placement="right"` (default) for detail panels and forms.
+- Use `placement="bottom"` for mobile-style bottom sheets.
+- Always include a `DrawerHeader` with a title.
+- For forms inside drawers, put action buttons in `DrawerFooter`.
+- Do not nest drawers within drawers. Use a dialog instead.

package/dist/guidelines/components/form.md ADDED Viewed

@@ -0,0 +1,100 @@
+# Form
+Form system built on react-hook-form + zod for validation.
+## Import
+```tsx
+import {
+  Form, FormField, FormItem, FormLabel,
+  FormControl, FormMessage, FormDescription,
+  FormRowContainer, FormHint, FormNestedContainer
+} from "@zscloud/design"
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+```
+## Standard pattern
+```tsx
+const schema = z.object({
+  name: z.string().min(1, "Required"),
+  email: z.string().email("Invalid email"),
+})
+type FormValues = z.infer<typeof schema>
+function MyForm() {
+  const form = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { name: "", email: "" },
+  })
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-col gap-3">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel required>Name</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel required>Email</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormDescription>We will not share your email.</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+      </form>
+    </Form>
+  )
+}
+```
+## Sub-components
+| Component | Purpose |
+|-----------|---------|
+| `Form` | Provider wrapper (react-hook-form FormProvider) |
+| `FormField` | Controller for a single field |
+| `FormItem` | Container for label + control + message |
+| `FormLabel` | Field label. Set `required` prop for asterisk |
+| `FormControl` | Wraps the input, connects aria attributes |
+| `FormMessage` | Validation error message |
+| `FormDescription` | Helper text below the input |
+| `FormHint` | Small hint text (text-xs) |
+| `FormRowContainer` | Horizontal layout for inline fields |
+| `FormNestedContainer` | Indented nested section with left border |
+| `FormRequiredIndicator` | Red asterisk (*) |
+## FormLabel props
+| Prop | Type | Description |
+|------|------|-------------|
+| `required` | `boolean` | Shows red asterisk |
+| `info` | `ReactNode` | Shows Info icon with tooltip |
+## Rules
+- Always use zod schemas for validation. Do not use manual validation logic.
+- Always wrap forms with the `Form` component.
+- Use `FormLabel` with `required` prop for mandatory fields. Do not manually add asterisks.
+- Use `FormMessage` for validation errors. Do not render errors manually.
+- Use `gap-3` (12px) between `FormItem` elements vertically.
+- Use `FormRowContainer` for side-by-side fields, not custom flex layouts.

package/dist/guidelines/components/select.md ADDED Viewed

@@ -0,0 +1,81 @@
+# Select
+Use for single-value selection from a list of options.
+## Import
+```tsx
+import { Select } from "@zscloud/design"
+```
+## Simple usage (recommended)
+```tsx
+const options = [
+  { label: "Option A", value: "a" },
+  { label: "Option B", value: "b", description: "With helper text" },
+]
+<Select
+  options={options}
+  value={value}
+  onValueChange={setValue}
+  placeholder="Select an option"
+/>
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `SelectOptions[]` | required | List of options |
+| `value` | `string` | - | Controlled value |
+| `defaultValue` | `string` | - | Uncontrolled default |
+| `onValueChange` | `(value: string) => void` | required | Change handler |
+| `placeholder` | `string` | - | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable interaction |
+| `allowClear` | `boolean` | `false` | Show clear button |
+| `onClear` | `() => void` | - | Clear handler |
+| `emptyPlaceholderText` | `string` | - | Text when no options |
+## Option shape
+```typescript
+interface SelectOptions {
+  label: ReactNode       // Display text in dropdown
+  selectedLabel?: ReactNode  // Display in trigger when selected (optional)
+  description?: string   // Secondary text below label
+  value: string          // Unique value
+}
+```
+## Composable usage (advanced)
+For custom layouts, use the primitive sub-components:
+```tsx
+import {
+  SelectRoot, SelectTrigger, SelectValue,
+  SelectContent, SelectGroup, SelectItem
+} from "@zscloud/design"
+<SelectRoot value={value} onValueChange={setValue}>
+  <SelectTrigger>
+    <SelectValue placeholder="Choose..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectItem value="a">Option A</SelectItem>
+      <SelectItem value="b">Option B</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</SelectRoot>
+```
+## Rules
+- Use the simple `Select` with `options` prop for standard cases.
+- Use the composable pattern only when you need custom item rendering.
+- For multi-selection, use `MultiSelect` instead.
+- For searchable selection, use `AutoComplete` instead.
+- For hierarchical selection, use `Cascader` instead.

package/dist/guidelines/components/tabs.md ADDED Viewed

@@ -0,0 +1,73 @@
+# Tabs
+Use for switching between related content panels.
+## Import
+```tsx
+import { Tabs } from "@zscloud/design"
+```
+## Simple usage
+```tsx
+const tabsList = [
+  { value: "overview", label: "Overview", content: <OverviewPanel /> },
+  { value: "config", label: "Configuration", content: <ConfigPanel /> },
+  { value: "logs", label: "Logs", content: <LogsPanel />, disabled: true },
+]
+<Tabs tabsList={tabsList} defaultValue="overview" />
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tabsList` | `TabsListItem[]` | required | Tab definitions |
+| `value` | `string` | - | Controlled active tab |
+| `defaultValue` | `string` | - | Initial active tab |
+| `onValueChange` | `(value: string) => void` | - | Tab change handler |
+| `variant` | `"line" \| "card" \| "outline"` | `"line"` | Visual style |
+| `forceMount` | `true` | - | Keep inactive tab DOM alive |
+| `contentId` | `string` | - | Enable tab state persistence |
+## TabsListItem
+```typescript
+interface TabsListItem {
+  value: string           // Unique identifier
+  label?: ReactNode       // Tab trigger text
+  content?: ReactNode     // Tab panel content
+  disabled?: boolean      // Disable this tab
+}
+```
+## Variants
+| Variant | Use for |
+|---------|---------|
+| `line` | Default. Underline indicator. Use in page sections. |
+| `card` | Card-style tabs. Use for container switching. |
+| `outline` | Bordered tabs. Use for compact layouts. |
+## Composable usage
+```tsx
+import { TabsRoot, TabsList, TabsTrigger, TabsContent } from "@zscloud/design"
+<TabsRoot defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">Content 1</TabsContent>
+  <TabsContent value="tab2">Content 2</TabsContent>
+</TabsRoot>
+```
+## Rules
+- Use the simple `Tabs` with `tabsList` prop for standard cases.
+- Use `forceMount` when tab panels contain stateful content that should not be destroyed.
+- Do not nest tabs within tabs. Use a different navigation pattern for deeper hierarchy.

package/dist/guidelines/components/toast.md ADDED Viewed

@@ -0,0 +1,60 @@
+# Toast
+Use for temporary notification messages (success, error, info).
+## Import
+```tsx
+import { toast, Toaster } from "@zscloud/design"
+```
+## Setup
+Add `Toaster` once at your application root:
+```tsx
+function App() {
+  return (
+    <>
+      <Toaster />
+      {/* App content */}
+    </>
+  )
+}
+```
+## Usage
+```tsx
+// Success
+toast({ title: "Resource created successfully", indicator: "success" })
+// Error
+toast({ title: "Failed to create resource", variant: "destructive" })
+// With description
+toast({
+  title: "Operation complete",
+  description: "3 resources were updated.",
+  indicator: "success",
+})
+// With action
+toast({
+  title: "Resource deleted",
+  action: <ToastAction altText="Undo">Undo</ToastAction>,
+})
+// Programmatic dismiss
+const { dismiss } = toast({ title: "Processing..." })
+// Later:
+dismiss()
+```
+## Rules
+- Always place `Toaster` at the application root, once.
+- Use `indicator: "success"` for success messages. Use `variant: "destructive"` for errors.
+- Keep toast messages concise (under 10 words for title).
+- Do not use toasts for critical errors that require user action. Use `Dialog` or `Alert` instead.
+- Toasts auto-dismiss. Do not set excessively long durations.

package/dist/guidelines/components/tooltip.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Tooltip
+Use for hover-triggered explanatory text. Do not use for interactive content.
+## Import
+```tsx
+import { Tooltip } from "@zscloud/design"
+```
+## Usage
+```tsx
+<Tooltip title="This is a helpful explanation">
+  <Button variant="ghost" size="icon">
+    <Icon type="info-circle" />
+  </Button>
+</Tooltip>
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `ReactNode` | required | Tooltip content |
+| `placement` | Position string | `"top"` | Where to show the tooltip |
+| `disappearOnClick` | `boolean` | `true` | Hide on click |
+| `delayDuration` | `number` | `0` | Delay before showing (ms) |
+## Placement options
+`topLeft`, `top`, `topRight`, `leftTop`, `left`, `leftBottom`, `rightTop`, `right`, `rightBottom`, `bottomLeft`, `bottom`, `bottomRight`
+## Rules
+- Use `Tooltip` for non-interactive explanatory text only.
+- For interactive content (links, buttons), use `Popover` instead.
+- Keep tooltip text concise (1-2 sentences max).
+- Do not put tooltips on disabled elements. Use the `Info` component for persistent hints.
+- Delay is 0ms by default. Do not add delay unless showing many tooltips in a dense area.

package/dist/guidelines/design-tokens/colors.md ADDED Viewed

@@ -0,0 +1,74 @@
+# Color Tokens
+## Semantic color system
+Use semantic color names, not raw hex values. The color system adapts automatically in dark mode.
+### Theme (brand) colors
+The primary brand color. Customizable at runtime via CSS variables.
+| Tailwind class | CSS variable | Default |
+|---------------|-------------|---------|
+| `bg-theme-500` | `--color-theme-500` | `#0076f7` (blue) |
+| `text-theme-600` | `--color-theme-600` | Darker brand |
+| `bg-theme-50` | `--color-theme-50` | Light brand tint |
+Full scale: `theme-50` through `theme-950`.
+### Status colors
+| Role | Tailwind prefix | Use for | Default base |
+|------|----------------|---------|-------------|
+| **danger** | `text-danger-500` | Errors, destructive actions | `#f4454c` (red) |
+| **positive** | `text-positive-500` | Success, healthy status | `#5aca49` (green) |
+| **alert** | `text-alert-500` | Warnings, caution | `#ff9000` (orange) |
+| **info** | `text-info-500` | Informational | `#0076f7` (blue) |
+| **pending** | `text-pending-500` | In-progress, waiting | `#9a45e4` (purple) |
+Each status color has a full scale from `50` to `950`.
+### Neutral colors
+For text, borders, backgrounds, and disabled states.
+| Usage | Tailwind class | Description |
+|-------|---------------|-------------|
+| Default text | `text-neutral-700` | Primary text |
+| Secondary text | `text-neutral-500` | Muted/helper text |
+| Disabled text | `text-neutral-400` | Disabled state |
+| Default border | `border-neutral-300` | Standard borders |
+| Subtle border | `border-neutral-200` | Subtle separation |
+| Hover background | `bg-neutral-100` | Hover state |
+| Page background | `bg-neutral-50` | Light background |
+Full scale: `neutral-0` (white) through `neutral-950` (near-black).
+### On-brand color
+Use `text-on-brand` for text on brand-colored backgrounds (buttons, badges). This is always white.
+## Semantic variables (CSS)
+These map to component default styles:
+| Variable | Light mode | Purpose |
+|----------|-----------|---------|
+| `--foreground` | `neutral-700` | Default text |
+| `--background` | `white` | Page background |
+| `--primary` | `theme-600` | Primary actions |
+| `--destructive` | `red-500` | Destructive actions |
+| `--border` | `neutral-300` | Default border |
+| `--input` | `neutral-400` | Input border |
+| `--ring` | `theme-300` | Focus ring |
+| `--muted` | `neutral-100` | Muted background |
+| `--muted-foreground` | `neutral-500` | Muted text |
+## Rules
+- Always use semantic color names (`danger`, `positive`, `alert`) instead of raw color names (`red`, `green`, `orange`).
+- Use `theme-*` for brand-related elements. Do not hardcode blue.
+- Use `neutral-*` for grays. Do not use arbitrary gray values.
+- For text on colored backgrounds, use `text-on-brand` (white).
+- For hover states, go one shade darker (e.g., `bg-theme-500` hover `bg-theme-600`).
+- For disabled states, reduce to `neutral-400` text and `neutral-200` background.

package/dist/guidelines/design-tokens/shadows.md ADDED Viewed

@@ -0,0 +1,28 @@
+# Shadow Tokens
+## Elevation scale
+| Tailwind class | Use for |
+|---------------|---------|
+| `shadow-2xs` | Subtle bottom border effect |
+| `shadow-xs` | Cards at rest |
+| `shadow-sm` | Raised cards, form controls on focus |
+| `shadow-md` | Dropdowns, popovers |
+| `shadow-lg` | Dialogs, drawers |
+| `shadow-xl` | Top-level modals |
+| `shadow-2xl` | Maximum elevation |
+## Focus rings
+| Tailwind class | Use for |
+|---------------|---------|
+| `shadow-focus-ring` | Default focus indicator (green tint) |
+| `shadow-focus-ring-error` | Error state focus indicator (red tint) |
+| `shadow-focus-ring-sidebar` | Sidebar-specific focus indicator (gray) |
+## Rules
+- Use `shadow-md` for all floating elements (popovers, dropdowns, context menus).
+- Use `shadow-lg` for dialogs and drawers.
+- Do not apply shadows to flat, inline elements.
+- Focus rings are applied automatically by components. Do not manually add focus ring styles.

package/dist/guidelines/design-tokens/spacing.md ADDED Viewed

@@ -0,0 +1,46 @@
+# Spacing Tokens
+The spacing system follows a 4px base grid. All spacing values are multiples of 4px.
+## Scale
+| Tailwind class | Value | Common use |
+|---------------|-------|------------|
+| `gap-0.5` / `p-0.5` | 2px | Tight internal spacing |
+| `gap-1` / `p-1` | 4px | Icon-to-text gap |
+| `gap-1.5` / `p-1.5` | 6px | Compact padding |
+| `gap-2` / `p-2` | 8px | Standard gap between related items |
+| `gap-3` / `p-3` | 12px | Form field gap, card padding |
+| `gap-4` / `p-4` | 16px | Section padding, standard margin |
+| `gap-6` / `p-6` | 24px | Section separation |
+| `gap-8` / `p-8` | 32px | Large section separation |
+## Component-specific spacing
+| Context | Spacing | Example |
+|---------|---------|---------|
+| Button icon gap | `gap-1` (4px) | Icon to label inside button |
+| Form field spacing | `gap-3` (12px) | Between form items vertically |
+| Dialog body padding | `p-4` (16px) | Content area padding |
+| Card content padding | `p-4` (16px) | Card body padding |
+| Page section gap | `gap-6` (24px) | Between major sections |
+| Inline elements | `gap-2` (8px) | Between buttons in a toolbar |
+## Border radius
+| Tailwind class | Value | Use for |
+|---------------|-------|---------|
+| `rounded-none` | 0px | No rounding |
+| `rounded-xs` | 2px | Inputs, buttons, cards (default) |
+| `rounded-sm` | 4px | Tags, badges |
+| `rounded-md` | 6px | Dialogs, dropdowns |
+| `rounded-lg` | 8px | Large containers |
+| `rounded-full` | 9999px | Circular elements, pills |
+## Rules
+- Always use the 4px grid. Do not use arbitrary spacing values like 5px or 7px.
+- Use `gap-*` for flex/grid layouts instead of margin on individual children.
+- The default border radius for interactive controls is `rounded-xs` (2px). Do not override unless specifically required.
+- Use `rounded-md` (6px) for floating elements (dialogs, popovers, dropdowns).
+- Use `rounded-full` only for avatars, status dots, and pill-shaped elements.

package/dist/guidelines/design-tokens/typography.md ADDED Viewed

@@ -0,0 +1,62 @@
+# Typography Tokens
+## Font families
+| Token | Tailwind class | Value |
+|-------|---------------|-------|
+| Sans (default) | `font-sans` | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "PingFang SC", Helvetica, Arial, sans-serif` |
+| Monospace | `font-mono` | `"SFMono-Medium", "SF Mono", "Segoe UI Mono", Menlo, Consolas, monospace` |
+Use `font-sans` for all UI text. Use `font-mono` only for code, UUIDs, and technical identifiers.
+## Font sizes
+| Token | Tailwind class | Size | Use for |
+|-------|---------------|------|---------|
+| xs | `text-xs` | 12px | Captions, helper text, badges |
+| sm | `text-sm` | 14px | Default body text, form labels, table cells |
+| base | `text-base` | 16px | Emphasized body text |
+| lg | `text-lg` | 20px | Section headings |
+| xl | `text-xl` | 24px | Page titles |
+| 2xl | `text-2xl` | 30px | Large headings |
+| 3xl | `text-3xl` | 38px | Hero headings |
+## Line heights
+| Token | Tailwind class | Value | Pair with |
+|-------|---------------|-------|-----------|
+| tight | `leading-tight` | 20px | `text-xs`, `text-sm` |
+| snug | `leading-snug` | 22px | `text-sm` |
+| normal | `leading-normal` | 24px | `text-base` |
+| relaxed | `leading-relaxed` | 28px | `text-lg` |
+| loose | `leading-loose` | 32px | `text-xl` |
+## Font weights
+| Tailwind class | Weight | Use for |
+|---------------|--------|---------|
+| `font-normal` | 400 | Body text |
+| `font-medium` | 500 | Labels, emphasis |
+| `font-semibold` | 600 | Headings, buttons |
+| `font-bold` | 700 | Strong emphasis |
+## Text component
+Use the `Text` component for consistent typography:
+```tsx
+import { Text } from "@zscloud/design"
+<Text variant="heading-lg">Page Title</Text>
+<Text variant="body">Regular text content</Text>
+<Text variant="caption" color="muted">Helper text</Text>
+```
+## Rules
+- The default font size for all UI controls is `text-sm` (14px). Do not use `text-xs` for form inputs or buttons.
+- Use `text-xs` (12px) only for captions, timestamps, and secondary metadata.
+- Do not use `text-base` (16px) or larger for table cell content.
+- Always pair font sizes with appropriate line heights. Use `leading-tight` for compact layouts.
+- Use `font-medium` (500) for form labels. Use `font-semibold` (600) for dialog titles and section headings.
+- Do not use letter-spacing adjustments unless specifically required for headings.

package/dist/guidelines/overview-components.md ADDED Viewed

@@ -0,0 +1,195 @@
+# Component Overview
+## Import pattern
+All components are named exports from the package root:
+```tsx
+import { Button, Dialog, Input, Select } from "@zscloud/design"
+```
+## Component categories
+### Form Controls
+| Component | Use for |
+|-----------|---------|
+| `Button` | Actions and submissions. Variants: primary, subtle, outline, secondary, danger, ghost, link |
+| `Input` | Single-line text input |
+| `InputNumber` | Numeric input with optional increment/decrement controls |
+| `InputPassword` | Password input with show/hide toggle |
+| `Textarea` | Multi-line text input |
+| `SearchInput` | Input with search icon, for filtering |
+| `Checkbox` | Boolean toggle. Supports indeterminate state |
+| `CheckboxGroup` | Multiple checkbox options |
+| `RadioGroup` | Single selection from options. Variants: basic, button |
+| `Select` | Single selection dropdown. Use `options` prop for simple usage |
+| `MultiSelect` | Multiple selection dropdown with tags |
+| `AutoComplete` | Input with suggestions dropdown |
+| `Cascader` | Hierarchical selection (province/city/district) |
+| `Switch` | Boolean toggle as a slider |
+| `Slider` | Range value selection |
+| `DatePicker` | Date selection with optional time picker |
+| `RangePicker` | Date range selection |
+| `TimePicker` | Time-only selection |
+| `Calendar` | Inline calendar display |
+| `Form` | Form container with validation. Built on react-hook-form + zod |
+### Data Display
+| Component | Use for |
+|-----------|---------|
+| `Tag` | Status labels and categories |
+| `TagList` | Multiple tags with overflow handling |
+| `Badge` | Notification count or dot indicator |
+| `StatusBadge` | Status indicator with semantic colors |
+| `Text` | Typography with variants (heading, body, caption) |
+| `Card` | Content container with header/body/footer sections |
+| `Collapse` | Expandable/collapsible content sections |
+| `Steps` | Multi-step process indicator |
+| `Progress` | Progress bar with percentage |
+| `Tree` | Hierarchical data display with expand/collapse |
+| `TreeSelect` | Tree-based selection dropdown |
+| `JsonViewer` | JSON data viewer with syntax highlighting |
+| `CodeEditor` | Code editing with syntax highlighting (CodeMirror) |
+| `Markdown` | Markdown content renderer |
+| `Divider` | Visual separator line |
+### Feedback
+| Component | Use for |
+|-----------|---------|
+| `Dialog` | Modal dialogs for confirmations, forms, and complex interactions |
+| `AlertDialog` | Simple confirm/cancel dialogs |
+| `Drawer` | Side panel overlay. Placement: right (default), left, top, bottom |
+| `Toast` | Temporary notification messages |
+| `Alert` | Inline alert messages |
+| `Spin` | Loading spinner overlay |
+| `Loader` | Inline loading indicator |
+| `PopoverConfirm` | Confirmation popover attached to a trigger |
+### Navigation
+| Component | Use for |
+|-----------|---------|
+| `Tabs` | Tab-based content switching. Variants: line, card, outline |
+| `Breadcrumb` | Navigation hierarchy |
+| `Pagination` | Page navigation with size selector |
+| `Link` | Styled anchor element |
+### Overlay
+| Component | Use for |
+|-----------|---------|
+| `Tooltip` | Hover information. 12 placement options |
+| `Popover` | Click-triggered content overlay |
+| `Dropdown` | Action menu triggered by button |
+| `ContextMenu` | Right-click context menu |
+### Layout
+| Component | Use for |
+|-----------|---------|
+| `ResizablePanelGroup` | Resizable split panes |
+| `ResizablePanel` | Individual panel within a group |
+| `ResizableHandle` | Drag handle between panels |
+### Business Components
+These are higher-level components for specific use cases:
+| Component | Use for |
+|-----------|---------|
+| `Field` | Labeled value display (label: value pairs) |
+| `FieldOperations` | Field with action buttons |
+| `State` | Resource state display with semantic colors |
+| `Info` | Info icon with tooltip explanation |
+| `InfoPopover` | Info icon with rich popover content |
+| `SmartTip` | Adaptive content display (truncate with expand) |
+| `Copy` | Copy-to-clipboard button |
+| `NoData` | Empty state placeholder |
+| `HeaderPage` | Page-level header with title and actions |
+| `HeaderDetail` | Detail page header with breadcrumb |
+| `HelperDoc` | Help documentation link |
+| `DateValue` | Formatted date display |
+| `ConfigProvider` | Global configuration provider |
+| `LocaleContainer` | i18n locale provider |
+| `AppBase` | Application root wrapper |
+## Common patterns
+### Form with validation
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage, Input, Button } from "@zscloud/design"
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+const schema = z.object({
+  name: z.string().min(1, "Name is required"),
+})
+function MyForm() {
+  const form = useForm({ resolver: zodResolver(schema) })
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel required>Name</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  )
+}
+```
+### Dialog with form
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogBody, Button } from "@zscloud/design"
+function MyDialog({ open, onOpenChange }) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Edit Resource</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          {/* Form content here */}
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="subtle" onClick={() => onOpenChange(false)}>Cancel</Button>
+          <Button>Confirm</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+### Select with options
+```tsx
+import { Select } from "@zscloud/design"
+const options = [
+  { label: "Option A", value: "a" },
+  { label: "Option B", value: "b", description: "With description" },
+]
+<Select options={options} value={value} onValueChange={setValue} placeholder="Select..." />
+```

package/dist/guidelines/overview-icons.md ADDED Viewed

@@ -0,0 +1,62 @@
+# Icon System
+The icon library provides 644 system icons and 38 app icons, all SVG-based.
+## Import
+```tsx
+import { Icon, AppIcon } from "@zscloud/design"
+```
+## System Icons (`Icon`)
+Use for inline UI icons (buttons, menus, status indicators).
+```tsx
+<Icon type="search" />
+<Icon type="arrow-down" />
+<Icon type="checkmark-circle-fill" color="positive" />
+<Icon type="close" color="danger" />
+```
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `IconName` | required | Kebab-case icon name |
+| `color` | `"neutral" \| "danger" \| "positive" \| "info" \| "alert" \| "pending"` | - | Semantic color |
+| `colorNumber` | `number` | - | Color shade (50-950) |
+Default size: 16x16px.
+### Commonly used icons
+**Navigation**: `arrow-left`, `arrow-right`, `arrow-up`, `arrow-down`, `chevron-left`, `chevron-right`, `chevron-down`, `chevron-up`
+**Actions**: `add`, `close`, `delete`, `edit`, `search`, `refresh`, `download`, `upload`, `copy`, `more`, `settings`
+**Status**: `checkmark-circle-fill`, `close-circle-fill`, `warning-fill`, `info-circle-fill`, `loading`
+**Content**: `file`, `folder`, `image`, `link`, `calendar`, `clock`, `user`, `lock`, `eye`, `eye-off`
+## App Icons (`AppIcon`)
+Use for application/module navigation icons. Larger, more detailed than system icons.
+```tsx
+<AppIcon type="settings" />
+<AppIcon type="hardware" />
+<AppIcon type="cloud-monitoring" />
+```
+Default size: 40x40px.
+### Available app icons
+`backup`, `settings`, `hardware`, `cloud-monitoring`, `ai-store`, `network-resource`, `network-service`, `vcenter`, `dashboard`, `virtual-orchestration`, `storage`, `tenant-management`, `zwatch-alarm`, `zwatch-endpoint`, `zwatch-monitor-group`, `zwatch-monitor-template`, and more.
+## Rules
+- Always use the `Icon` component instead of raw SVG or icon fonts.
+- Use semantic `color` prop for status-related icons. Do not apply Tailwind color classes directly to icons.
+- Do not resize icons with `width`/`height` attributes. Use the Tailwind `size-*` class on a wrapper if needed.

package/dist/zscloud-design.es.js CHANGED Viewed

@@ -19032,7 +19032,7 @@ var SelectEmptyPlaceholder = (e) => {
 });
 InputNumber.displayName = "InputNumber";
 var Pagination = (e) => {
-	let { pagination: t, setPagination: n, count: i } = e, o = useIntl(), l = Math.ceil(i / t.pageSize), [u, d] = useState(""), f = useId$1();
+	let { pagination: t, setPagination: n, count: i } = e, o = useIntl(), l = Math.ceil(i / t.pageSize), [u, d] = useState(""), f = useRef(null);
 	return /* @__PURE__ */ jsxs("div", {
 		className: "flex items-center gap-6 h-8",
 		children: [/* @__PURE__ */ jsx(PaginationRoot, {
@@ -19092,7 +19092,7 @@ var Pagination = (e) => {
 			})
 		}), /* @__PURE__ */ jsxs("div", {
 			className: "items-center text-sm flex gap-4 h-8",
-			id: `pagination-select-container-${f}`,
+			ref: f,
 			children: [/* @__PURE__ */ jsxs(SelectRoot, {
 				value: t.pageSize + "",
 				onValueChange: (e) => {
@@ -19105,7 +19105,7 @@ var Pagination = (e) => {
 					className: "w-auto text-nowrap h-8",
 					children: /* @__PURE__ */ jsx(SelectValue, {})
 				}), /* @__PURE__ */ jsx(SelectContent, {
-					selectPortalProps: { container: document.getElementById(`pagination-select-container-${f}`) },
+					selectPortalProps: { container: f.current },
 					children: /* @__PURE__ */ jsxs(SelectGroup, { children: [
 						/* @__PURE__ */ jsx(SelectItem, {
 							value: "10",
@@ -23761,34 +23761,42 @@ var cardVariants = cva("rounded-xs w-full box-border h-min bg-neutral-0", {
 	defaultVariants: { variant: "default" }
 }), CardContext = createContext({
 	isCollapsed: !1,
-	toggleCollapse: () => {}
+	toggleCollapse: () => {},
+	variant: "default"
 });
 function useCardContext() {
 	return useContext(CardContext);
 }
-function CardProvider({ children: e }) {
-	let [t, n] = useState(!1);
+function CardProvider({ children: e, variant: t }) {
+	let [n, i] = useState(!1);
 	return /* @__PURE__ */ jsx(CardContext.Provider, {
 		value: {
-			isCollapsed: t,
+			isCollapsed: n,
 			toggleCollapse: () => {
-				n(!t);
-			}
+				i(!n);
+			},
+			variant: t
 		},
 		children: e
 	});
 }
-var Card = React$1.forwardRef(({ className: e, variant: t, ...n }, i) => /* @__PURE__ */ jsx(CardProvider, { children: /* @__PURE__ */ jsx("div", {
-	ref: i,
-	className: cn(cardVariants({ variant: t }), e),
-	...n
-}) }));
-Card.displayName = "Card";
-var CardHeader = React$1.forwardRef(({ className: e, ...t }, n) => /* @__PURE__ */ jsx("div", {
-	ref: n,
-	className: cn("flex bg-transparent text-neutral-700 w-full items-center px-6 py-3 box-border justify-between border-b border-solid border-neutral-300", e),
-	...t
+var Card = React$1.forwardRef(({ className: e, variant: t, ...n }, i) => /* @__PURE__ */ jsx(CardProvider, {
+	variant: t,
+	children: /* @__PURE__ */ jsx("div", {
+		ref: i,
+		className: cn(cardVariants({ variant: t }), e),
+		...n
+	})
 }));
+Card.displayName = "Card";
+var CardHeader = React$1.forwardRef(({ className: e, ...t }, n) => {
+	let { variant: i } = useCardContext();
+	return /* @__PURE__ */ jsx("div", {
+		ref: n,
+		className: cn("flex text-neutral-700 w-full items-center box-border justify-between", i === "default" || i === "detail" || !i ? "bg-neutral-100 h-9.5 px-5" : "bg-transparent px-6 py-3", e),
+		...t
+	});
+});
 CardHeader.displayName = "CardHeader";
 var CardTitle = React$1.forwardRef(({ className: e, ...t }, n) => /* @__PURE__ */ jsx("div", {
 	ref: n,
@@ -32122,7 +32130,7 @@ var CollapseContent = React$1.forwardRef(({ className: t, forceRender: n = !1, .
 	});
 });
 CollapseContent.displayName = "CollapseContent";
-var alertVariants = cva("flex items-center relative flex-row px-4 py-2.5 rounded-xs", {
+var alertVariants = cva("flex items-start relative flex-row px-4 py-2.5 rounded-xs", {
 	variants: {
 		variant: {
 			danger: "bg-danger-50",
@@ -32152,7 +32160,7 @@ var alertVariants = cva("flex items-center relative flex-row px-4 py-2.5 rounded
 		m(!1), u == null || u();
 	}, [u]);
 	if (!p) return null;
-	let g = cn("mr-2 min-h-4 min-w-4 shrink-0", i === "weak" && "mr-1.5");
+	let g = cn("mr-2 min-h-4 min-w-4 shrink-0", i === "weak" ? "mr-1.5" : "mt-0.5");
 	return /* @__PURE__ */ jsxs("div", {
 		ref: f,
 		className: alertVariants({
@@ -32162,7 +32170,7 @@ var alertVariants = cva("flex items-center relative flex-row px-4 py-2.5 rounded
 		}),
 		...d,
 		children: [/* @__PURE__ */ jsxs("div", {
-			className: cn("text-neutral-700 text-sm flex flex-row flex-1", i === "weak" && "text-xs text-neutral-500"),
+			className: cn("text-neutral-700 text-sm flex flex-row items-start flex-1", i === "weak" && "text-xs text-neutral-500"),
 			children: [
 				n === "danger" && /* @__PURE__ */ jsx(alert_triangle_fillreact$1, { className: cn(g, "text-danger-500") }),
 				n === "warning" && /* @__PURE__ */ jsx(alert_triangle_fillreact$1, { className: cn(g, "text-alert-500") }),

package/package.json CHANGED Viewed

@@ -1,11 +1,12 @@
 {
   "name": "@zscloud/design",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A modern React component library built with Radix UI and Tailwind CSS V4",
   "type": "module",
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "dist/guidelines"
   ],
   "typings": "./dist/index.d.ts",
   "module": "./dist/zscloud-design.es.js",