create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/ui-kit/src/ui/tree-table/index.tsx

@@ -0,0 +1,229 @@
+// TreeTable — cây đệ quy dạng bảng kiểu PrimeReact TreeTable: data lồng children,
+// expander chevron xoay 90, indent theo depth (bước bước --sp-4), selection
+// single/checkbox theo ngôn ngữ Table (bg-accent/10 + hover:bg-s3 + header select-all).
+// Animation mở rộng: đúng KẶC 3 tầng grid > min-h-0 overflow-hidden > content
+// (pattern fix padding-leak V2 của Collapse — track 0fr phải clip SẠCH padding).
+// A11y: role=treegrid + rowgroup/row/cell, aria-level + aria-expanded trên row,
+// expander là <button aria-expanded aria-label>; row selected → aria-selected.
+import { useState, type CSSProperties, type ReactNode } from 'react';
+import { Checkbox } from '../checkbox/index';
+import { EmptyState } from '../empty-state/index';
+import { Icon } from '../icons/index.js';
+
+export interface TreeTableNode {
+  /** Khóa định danh của node (selection/expandedKeys dùng). */
+  key: string;
+  /** Node con — lồng không giới hạn cấp. */
+  children?: TreeTableNode[];
+  /** Giá trị các cột: key = column.key. */
+  values: Record<string, ReactNode>;
+}
+
+export interface TreeTableColumn {
+  /** Khóa cột — khớp key trong node.values. */
+  key: string;
+  /** Tiêu đề cột (header row). */
+  header: ReactNode;
+  /** Căn nội dung ô (mặc định left). */
+  align?: 'left' | 'center' | 'right';
+  /** Render custom — nhận node (và depth nếu cần). */
+  render?: (node: TreeTableNode, depth: number) => ReactNode;
+}
+
+export interface TreeTableProps {
+  /** Cây dữ liệu — node không có children render như lá (không expander). */
+  data: TreeTableNode[];
+  columns: TreeTableColumn[];
+  /** Chọn hàng: none | single (click) | checkbox (cột + select-all). */
+  selectionMode?: 'none' | 'single' | 'checkbox';
+  /** Keys đang chọn (controlled) — đi kèm onSelectionChange. */
+  selectedKeys?: string[];
+  /** Callback chọn đổi — mảng keys đầy đủ. */
+  onSelectionChange?: (keys: string[]) => void;
+  /** Nhánh đang mở (controlled). */
+  expandedKeys?: string[];
+  /** Nhánh mở mặc định (uncontrolled — đọc lúc mount). */
+  defaultExpandedKeys?: string[];
+  /** Callback mở/đóng nhánh — mảng keys đang mở sau toggle. */
+  onRowToggle?: (keys: string[]) => void;
+  /** Nội dung khi data rỗng (mặc định EmptyState). */
+  emptyMessage?: ReactNode;
+  className?: string;
+}
+
+/** Thu toàn bộ keys của cây (select-all dùng). */
+function collectKeys(nodes: TreeTableNode[]): string[] {
+  const out: string[] = [];
+  const walk = (list: TreeTableNode[]) => {
+    for (const n of list) {
+      out.push(n.key);
+      if (n.children) walk(n.children);
+    }
+  };
+  walk(nodes);
+  return out;
+}
+
+const CELL = 'px-4 py-2.5 text-body'; // chuẩn cell Table size normal
+
+export function TreeTable({
+  data,
+  columns,
+  selectionMode = 'none',
+  selectedKeys: controlledSelected,
+  onSelectionChange,
+  expandedKeys: controlledExpanded,
+  defaultExpandedKeys = [],
+  onRowToggle,
+  emptyMessage,
+  className,
+}: TreeTableProps) {
+  const [innerExpanded, setInnerExpanded] = useState<Set<string>>(() => new Set(defaultExpandedKeys));
+  const [innerSelected, setInnerSelected] = useState<string[]>([]);
+  const openSet = controlledExpanded ? new Set(controlledExpanded) : innerExpanded;
+  const selected = controlledSelected ?? innerSelected;
+
+  const gridCols = `40px ${columns.map(() => 'minmax(0, 1fr)').join(' ')}`;
+
+  function toggleExpand(key: string) {
+    const next = new Set(openSet);
+    if (next.has(key)) next.delete(key);
+    else next.add(key);
+    if (!controlledExpanded) setInnerExpanded(next);
+    onRowToggle?.([...next]);
+  }
+
+  function emitSelection(keys: string[]) {
+    if (!controlledSelected) setInnerSelected(keys);
+    onSelectionChange?.(keys);
+  }
+
+  function toggleRow(key: string) {
+    emitSelection(selected.includes(key) ? selected.filter((k) => k !== key) : [...selected, key]);
+  }
+
+  const allSelected = data.length > 0 && collectKeys(data).every((k) => selected.includes(k));
+
+  /** Render 1 node + subtree: row, rồi 3 tầng grid clip phần children. */
+  const renderNode = (node: TreeTableNode, depth: number): ReactNode => {
+    const isBranch = (node.children?.length ?? 0) > 0;
+    const open = openSet.has(node.key);
+    const isSelected = selected.includes(node.key);
+    const rowStyle: CSSProperties = { gridTemplateColumns: gridCols };
+    return (
+      <div key={node.key} role="rowgroup">
+        <div
+          role="row"
+          aria-level={depth + 1}
+          aria-selected={selectionMode !== 'none' ? isSelected : undefined}
+          aria-expanded={isBranch ? open : undefined}
+          data-key={node.key}
+          style={rowStyle}
+          className={`grid border-b border-line2 transition-colors duration-150 ${
+            isSelected ? 'bg-accent/10' : ''
+          } hover:bg-s3 ${selectionMode === 'single' ? 'cursor-pointer' : ''}`}
+          onClick={() => selectionMode === 'single' && toggleRow(node.key)}
+        >
+          {selectionMode === 'checkbox' && (
+            <div role="gridcell" className={`${CELL} w-10`} onClick={(e) => e.stopPropagation()}>
+              <Checkbox
+                aria-label={`Chọn ${node.key}`}
+                checked={isSelected}
+                onChange={() => toggleRow(node.key)}
+              />
+            </div>
+          )}
+          <div role="gridcell" className={`${CELL} flex items-center`} style={{ paddingLeft: `calc(var(--sp-4) * ${depth})` }}>
+            {isBranch ? (
+              <button
+                type="button"
+                aria-expanded={open}
+                aria-label={`${open ? 'Đóng' : 'Mở'} ${node.key}`}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  toggleExpand(node.key);
+                }}
+                className="cursor-pointer border-none bg-transparent p-0 text-ink3 transition-colors hover:text-ink active:opacity-70 focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:outline-none"
+              >
+                {/* Expander xoay 90 như expander Table */}
+                <span className={`inline-grid place-items-center transition-transform duration-200 ${open ? 'rotate-90' : ''}`}>
+                  <Icon name="chevron-right" size={12} />
+                </span>
+              </button>
+            ) : (
+              <span className="inline-block w-3" aria-hidden="true" />
+            )}
+          </div>
+          {columns.map((col) => (
+            <div
+              key={col.key}
+              role="gridcell"
+              className={`${CELL} ${col.align === 'right' ? 'text-right' : col.align === 'center' ? 'text-center' : ''}`}
+            >
+              {col.render ? col.render(node, depth) : node.values[col.key] ?? ''}
+            </div>
+          ))}
+        </div>
+        {isBranch && (
+          <div
+            className={`grid transition-[grid-template-rows] duration-200 ${open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'}`}
+          >
+            {/* 3 tầng: clip nằm SẠCH padding — subtree nằm trong min-h-0 overflow-hidden
+             * (pattern V2: để padding trên element clip ⇒ track 0fr vẫn lộ chiều cao). */}
+            <div className="min-h-0 overflow-hidden">
+              <div>{node.children!.map((child) => renderNode(child, depth + 1))}</div>
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  return (
+    <div
+      role="treegrid"
+      aria-readonly={selectionMode === 'none' ? undefined : false}
+      className={`overflow-auto rounded-xl border border-line${className ? ` ${className}` : ''}`}
+    >
+      {/* Header row — cùng grid template với body rows */}
+      <div role="rowgroup" aria-hidden="false">
+        <div
+          role="row"
+          style={{ gridTemplateColumns: selectionMode === 'checkbox' ? `40px ${gridCols}` : gridCols }}
+          className="grid bg-s3"
+        >
+          {selectionMode === 'checkbox' && (
+            <div role="columnheader" className={`${CELL} w-10`}>
+              <Checkbox
+                aria-label="Chọn tất cả"
+                checked={allSelected}
+                onChange={() => emitSelection(allSelected ? [] : collectKeys(data))}
+              />
+            </div>
+          )}
+          <div role="columnheader" className={CELL} aria-label="Mở rộng" />
+          {columns.map((col) => (
+            <div
+              key={col.key}
+              role="columnheader"
+              className={`${CELL} font-semibold text-ink2 ${col.align === 'right' ? 'text-right' : col.align === 'center' ? 'text-center' : ''}`}
+            >
+              {col.header}
+            </div>
+          ))}
+        </div>
+      </div>
+      <div role="rowgroup">
+        {data.length === 0 ? (
+          <div role="row" style={{ gridTemplateColumns: '1fr' }}>
+            <div role="gridcell" className={CELL}>
+              {emptyMessage ?? <EmptyState title="Không có dữ liệu" />}
+            </div>
+          </div>
+        ) : (
+          data.map((node) => renderNode(node, 0))
+        )}
+      </div>
+    </div>
+  );
+}

package/stack-template/app/ui-kit/src/ui/tree-table/tree-table.stories.tsx

@@ -0,0 +1,111 @@
+// TreeTable stories — org tree, custom render, controlled selection, empty.
+// Parity matrix PrimeReact→tokens: docs/parity-matrix.md
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Tag } from '../tag/index.js';
+import { TreeTable, type TreeTableNode } from './index';
+
+/** Tree data in a table grid — rows expandable by hierarchy. */
+const meta = {
+  title: 'Data Display/TreeTable',
+  tags: ['autodocs'],
+} satisfies Meta;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const FS: TreeTableNode[] = [
+  {
+    key: 'src',
+    values: { name: 'src', kind: 'dir', size: '—' },
+    children: [
+      {
+        key: 'ui',
+        values: { name: 'ui', kind: 'dir', size: '—' },
+        children: [
+          { key: 'button', values: { name: 'button.tsx', kind: 'tsx', size: '8 KB' } },
+          { key: 'table', values: { name: 'table.tsx', kind: 'tsx', size: '31 KB' } },
+        ],
+      },
+      { key: 'hooks', values: { name: 'hooks.ts', kind: 'ts', size: '4 KB' } },
+    ],
+  },
+  { key: 'readme', values: { name: 'README.md', kind: 'md', size: '2 KB' } },
+];
+
+const COLS = [
+  { key: 'name', header: 'Name' },
+  { key: 'size', header: 'Size', align: 'right' as const },
+];
+
+export const Basic: Story = {
+  name: 'Basic — file tree, expand via chevron (single column level indent)',
+  render: () => <TreeTable data={FS} columns={COLS} defaultExpandedKeys={['src']} />,
+};
+
+export const CustomRender: Story = {
+  name: 'Custom render — kind column as Tag, right-aligned size',
+  render: () => (
+    <TreeTable
+      data={FS}
+      columns={[
+        { key: 'name', header: 'Name' },
+        {
+          key: 'kind',
+          header: 'Kind',
+          render: (n) => (n.values.kind === 'dir' ? <Tag>dir</Tag> : <span className="text-meta text-ink3">{String(n.values.kind)}</span>),
+        },
+        { key: 'size', header: 'Size', align: 'right' },
+      ]}
+      defaultExpandedKeys={['src', 'ui']}
+    />
+  ),
+};
+
+export const RowSelection: Story = {
+  name: 'Row selection — checkbox column + select-all (includes collapsed nodes)',
+  render: () => {
+    function Demo() {
+      const [sel, setSel] = useState<string[]>([]);
+      return (
+        <div className="flex flex-col gap-3">
+          <TreeTable
+            data={FS}
+            columns={COLS}
+            selectionMode="checkbox"
+            selectedKeys={sel}
+            onSelectionChange={setSel}
+            defaultExpandedKeys={['src']}
+          />
+          <div className="text-meta text-ink3">selected: {JSON.stringify(sel)}</div>
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const SingleSelection: Story = {
+  name: 'Single selection — click a row to highlight (accent tint)',
+  render: () => {
+    function Demo() {
+      const [sel, setSel] = useState<string[]>(['readme']);
+      return <TreeTable data={FS} columns={COLS} selectionMode="single" selectedKeys={sel} onSelectionChange={setSel} />;
+    }
+    return <Demo />;
+  },
+};
+
+export const Empty: Story = {
+  name: 'Empty — no data falls back to EmptyState',
+  render: () => <TreeTable data={[]} columns={COLS} />,
+};
+
+export const DarkTheme: Story = {
+  name: 'DarkTheme — surface/border/selection follow tokens',
+  render: () => (
+    <div data-bp-theme="dark" className="p-4">
+      <TreeTable data={FS} columns={COLS} defaultExpandedKeys={['src', 'ui']} selectionMode="single" />
+    </div>
+  ),
+};

package/stack-template/app/ui-kit/src/ui/tree-table/tree-table.test.tsx

@@ -0,0 +1,137 @@
+// TreeTable tests — render cây, expand/collapse + onRowToggle, indent depth,
+// selection single/checkbox + select-all, render cell custom, align, empty,
+// controlled expandedKeys, a11y treegrid (aria-level/expanded/selected).
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TreeTable, type TreeTableNode } from './index.js';
+
+const TREE: TreeTableNode[] = [
+  {
+    key: 'root',
+    values: { name: 'Root', size: '—' },
+    children: [
+      {
+        key: 'src',
+        values: { name: 'src', size: '2MB' },
+        children: [{ key: 'app', values: { name: 'app.tsx', size: '4KB' } }],
+      },
+      { key: 'readme', values: { name: 'README.md', size: '1KB' } },
+    ],
+  },
+];
+
+const COLS = [
+  { key: 'name', header: 'Name' },
+  { key: 'size', header: 'Size', align: 'right' as const },
+];
+
+afterEach(cleanup);
+
+const row = (k: string) => screen.getByRole('row', { name: new RegExp(k, 'i') });
+
+describe('TreeTable', () => {
+  it('render node gốc + node lá; mặc định subtree GỤP (track 0fr, aria-expanded=false)', () => {
+    render(<TreeTable data={TREE} columns={COLS} />);
+    expect(row('root')).toBeInTheDocument();
+    expect(row('readme')).toBeInTheDocument();
+    // 3-tier pattern: subtree vẫn trong DOM (clip), trạng thái đọc qua row + wrapper
+    const srcRow = row('src');
+    expect(srcRow).toHaveAttribute('aria-expanded', 'false');
+    expect(srcRow.nextElementSibling!.className).toContain('grid-rows-[0fr]');
+  });
+
+  it('expand: click chevron → con xuất hiện, aria-expanded=true, chevron rotate-90', () => {
+    render(<TreeTable data={TREE} columns={COLS} />);
+    const btn = screen.getByRole('button', { name: 'Mở root' });
+    expect(btn).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.click(btn);
+    expect(btn).toHaveAttribute('aria-expanded', 'true');
+    expect(document.querySelector('[data-key="src"]')).not.toBeNull();
+    // 3-tier: cháu vẫn trong DOM nhưng bị clip — wrapper của src còn track 0fr
+    const srcRow = screen.getByRole("row", { name: /src/i });
+    expect(srcRow).toHaveAttribute("aria-expanded", "false");
+    expect(srcRow.nextElementSibling!.className).toContain("grid-rows-[0fr]");
+    // chevron xoay
+    expect((btn.firstElementChild as HTMLElement).className).toContain('rotate-90');
+  });
+
+  it('defaultExpandedKeys → mở sẵn cả 2 cấp', () => {
+    render(<TreeTable data={TREE} columns={COLS} defaultExpandedKeys={['root', 'src']} />);
+    expect(document.querySelector('[data-key="app"]')).not.toBeNull();
+  });
+
+  it('collapse lại: click lần 2 → subtree rời DOM + onRowToggle payload', () => {
+    const onRowToggle = vi.fn();
+    render(<TreeTable data={TREE} columns={COLS} onRowToggle={onRowToggle} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Mở root' }));
+    expect(onRowToggle).toHaveBeenLastCalledWith(['root']);
+    fireEvent.click(screen.getByRole('button', { name: 'Đóng root' }));
+    expect(onRowToggle).toHaveBeenLastCalledWith([]);
+    const srcRow = row('src');
+    expect(srcRow).toHaveAttribute('aria-expanded', 'false');
+    expect(srcRow.nextElementSibling!.className).toContain('grid-rows-[0fr]');
+  });
+
+  it('controlled expandedKeys: click KHÔNG tự đổi — chỉ bắn onRowToggle', () => {
+    const onRowToggle = vi.fn();
+    render(<TreeTable data={TREE} columns={COLS} expandedKeys={['root']} onRowToggle={onRowToggle} />);
+    expect(document.querySelector('[data-key="src"]')).not.toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'Đóng root' }));
+    expect(onRowToggle).toHaveBeenCalledWith([]);
+    expect(document.querySelector('[data-key="src"]')).not.toBeNull(); // vẫn theo prop
+  });
+
+  it('indent theo depth: cell expander con có padding-left = sp-4 × depth', () => {
+    render(<TreeTable data={TREE} columns={COLS} defaultExpandedKeys={['root']} />);
+    const rootCell = row('root').firstElementChild as HTMLElement;
+    const srcCell = document.querySelector('[data-key="src"] [role="gridcell"]') as HTMLElement;
+    expect(rootCell.style.paddingLeft).toBe('calc(var(--sp-4) * 0)');
+    expect(srcCell.style.paddingLeft).toBe('calc(var(--sp-4) * 1)');
+  });
+
+  it('selectionMode single: click row → aria-selected + onSelectionChange([key])', () => {
+    const onSelectionChange = vi.fn();
+    render(<TreeTable data={TREE} columns={COLS} selectionMode="single" onSelectionChange={onSelectionChange} />);
+    fireEvent.click(row('readme'));
+    expect(onSelectionChange).toHaveBeenCalledWith(['readme']);
+    expect(row('readme')).toHaveAttribute('aria-selected', 'true');
+    expect((row('readme') as HTMLElement).className).toContain('bg-accent/10');
+  });
+
+  it('selectionMode checkbox: toggle từng hàng + select-all chọn toàn cây', () => {
+    const onSelectionChange = vi.fn();
+    render(
+      <TreeTable data={TREE} columns={COLS} selectionMode="checkbox" defaultExpandedKeys={['root', 'src']} onSelectionChange={onSelectionChange} />,
+    );
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Chọn readme' }));
+    expect(onSelectionChange).toHaveBeenLastCalledWith(['readme']);
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Chọn tất cả' }));
+    expect(onSelectionChange).toHaveBeenLastCalledWith(['root', 'src', 'app', 'readme']);
+  });
+
+  it('render cell custom + align right nhận class text-right', () => {
+    render(
+      <TreeTable
+        data={TREE}
+        columns={[
+          { key: 'name', header: 'Name', render: (n) => <strong>{n.values.name}!</strong> },
+          { key: 'size', header: 'Size', align: 'right' },
+        ]}
+        defaultExpandedKeys={['root']}
+      />,
+    );
+    expect(screen.getByText('README.md!')).toBeInTheDocument();
+    const sizeCell = row('readme').lastElementChild as HTMLElement;
+    expect(sizeCell.className).toContain('text-right');
+  });
+
+  it('a11y treegrid: aria-level + rowgroup + empty → EmptyState', () => {
+    render(<TreeTable data={TREE} columns={COLS} defaultExpandedKeys={['root']} />);
+    expect(document.querySelector('[role="treegrid"]')).not.toBeNull();
+    expect(row('root')).toHaveAttribute('aria-level', '1');
+    expect(document.querySelector('[data-key="app"]')!).toHaveAttribute('aria-level', '3');
+    const { unmount } = render(<TreeTable data={[]} columns={COLS} />);
+    expect(screen.getByText('Không có dữ liệu')).toBeInTheDocument();
+    unmount();
+  });
+});

package/stack-template/app/ui-kit/src/ui/typography/index.tsx

@@ -0,0 +1,124 @@
+// Typography — antd composite: Typography.Title (level 1–5: 38/30/24/20/16 semibold,
+// margin-bottom .5em) · Text (secondary/success/warning/danger, strong/code/underline/
+// delete/keyboard, copyable-lite) · Paragraph. Metrics từ antd typography default.
+import { useCallback, useRef, type CSSProperties, type ReactNode } from 'react';
+
+const TITLE_SIZE: Record<number, number> = { 1: 38, 2: 30, 3: 24, 4: 20, 5: 16 };
+const TITLE_TAG: Record<number, 'h1' | 'h2' | 'h3' | 'h4' | 'h5'> = { 1: 'h1', 2: 'h2', 3: 'h3', 4: 'h4', 5: 'h5' };
+
+export interface TitleProps {
+  level?: 1 | 2 | 3 | 4 | 5;
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Title({ level = 1, children, className, style }: TitleProps) {
+  const Tag = TITLE_TAG[level];
+  return (
+    <Tag
+      className={className}
+      style={{ fontSize: TITLE_SIZE[level], fontWeight: level === 1 ? 700 : 600, lineHeight: 1.25, marginBottom: '0.5em', color: 'var(--ink)', ...style }}
+    >
+      {children}
+    </Tag>
+  );
+}
+
+export type TextType = 'secondary' | 'success' | 'warning' | 'danger';
+
+const TYPE_COLOR: Record<TextType, string> = {
+  secondary: 'var(--ink2)',
+  success: 'var(--st-done)',
+  warning: 'var(--st-doing)',
+  danger: 'var(--st-fail)',
+};
+
+export interface TextProps {
+  children: ReactNode;
+  type?: TextType;
+  strong?: boolean;
+  code?: boolean;
+  underline?: boolean;
+  delete?: boolean;
+  keyboard?: boolean;
+  /** Copy vào clipboard khi click + tooltip title "Copy" (antd copyable-lite). */
+  copyable?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Text({
+  children,
+  type,
+  strong,
+  code,
+  underline,
+  delete: del,
+  keyboard,
+  copyable,
+  className,
+  style,
+}: TextProps) {
+  const typeStyle = type ? { color: TYPE_COLOR[type] } : undefined;
+  let content: ReactNode = children;
+  if (code) content = <code style={{ fontFamily: 'var(--m)', fontSize: '0.9em', background: 'var(--s3)', padding: '0.2em 0.4em', borderRadius: 4 }}>{content}</code>;
+  if (keyboard) content = <kbd style={{ fontFamily: 'var(--m)', fontSize: '0.9em', border: '1px solid var(--line)', borderBottomWidth: 2, borderRadius: 4, padding: '0 4px' }}>{content}</kbd>;
+  if (underline) content = <u>{content}</u>;
+  if (del) content = <del>{content}</del>;
+  if (strong) content = <strong>{content}</strong>;
+
+  const ref = useRef<HTMLSpanElement>(null);
+  const onCopy = useCallback(() => {
+    if (!copyable) return;
+    // copy textContent — đúng nội dung user thấy (children có thể là node)
+    void navigator.clipboard?.writeText(ref.current?.textContent ?? '');
+  }, [copyable]);
+
+  return (
+    <span
+      style={{ cursor: copyable ? 'pointer' : undefined }}
+      title={copyable ? 'Copy' : undefined}
+      onClick={copyable ? onCopy : undefined}
+    >
+      <span
+        ref={ref}
+        className={className}
+        style={{ color: 'var(--ink)', ...typeStyle, ...style }}
+      >
+        {content}
+      </span>
+      {copyable && (
+        <span aria-hidden="true" style={{ marginLeft: 4, color: 'var(--ink3)', fontSize: '0.9em' }}>
+          ⧉
+        </span>
+      )}
+    </span>
+  );
+}
+
+export interface ParagraphProps {
+  children: ReactNode;
+  type?: TextType;
+  strong?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Paragraph({ children, type, strong, className, style }: ParagraphProps) {
+  return (
+    <p
+      className={className}
+      style={{ margin: 0, lineHeight: 1.6, color: type ? TYPE_COLOR[type] : 'var(--ink)', fontWeight: strong ? 600 : undefined, ...style }}
+    >
+      {children}
+    </p>
+  );
+}
+
+/** Typography composite — pattern antd (Typography.Title/Text/Paragraph). */
+// eslint-disable-next-line react-refresh/only-export-components
+export const Typography = Object.assign(
+  () => null,
+  { Title, Text, Paragraph },
+);

package/stack-template/app/ui-kit/src/ui/typography/typography.stories.tsx

@@ -0,0 +1,65 @@
+// Parity matrix antd→tokens: docs/parity-matrix.md
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Typography } from './index';
+
+const { Title, Text, Paragraph } = Typography;
+
+/** Text primitives — Title/Text/Paragraph with type colors. */
+const meta = {
+  title: 'Primitives/Typography',
+  
+  tags: ['autodocs'],
+} satisfies Meta;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const CacCapTitle: Story = {
+  name: 'Title — level 1–5',
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Title level={1}>H1 — Trang (38px)</Title>
+      <Title level={2}>H2 — Section (30px)</Title>
+      <Title level={3}>H3 — Panel (24px)</Title>
+      <Title level={4}>H4 — Nhóm (20px)</Title>
+      <Title level={5}>H5 — Nhỏ (16px)</Title>
+    </div>
+  ),
+};
+
+export const TextKieuMau: Story = {
+  name: 'Text — color types + strong',
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Text>Text mặc định (default)</Text>
+      <Text type="secondary">Text secondary (nhạt — mô tả)</Text>
+      <Text type="success">Text success (thành công)</Text>
+      <Text type="warning">Text warning (cảnh báo)</Text>
+      <Text type="danger">Text danger (lỗi)</Text>
+      <Text strong>Text strong (đậm)</Text>
+    </div>
+  ),
+};
+
+export const TextTrangTri: Story = {
+  name: 'Text — underline/delete/code/keyboard + copyable',
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Text underline>Gạch dưới (underline)</Text>
+      <Text delete>Gạch ngang (delete)</Text>
+      <Text code>Đoạn code inline</Text>
+      <Text keyboard>Ctrl</Text> + <Text keyboard>K</Text>
+      <Text copyable>Nội dung copy được — click icon để copy</Text>
+    </div>
+  ),
+};
+
+export const ParagraphMacDinh: Story = {
+  name: 'Paragraph — body block',
+  render: () => (
+    <Paragraph>
+      Đoạn văn bản dài — Typography giữ metrics antd: fontSize 14, lineHeight thoáng,
+      màu mực chính. Dùng cho nội dung thân bài, mô tả dài trong panel.
+    </Paragraph>
+  ),
+};