@usefragments/ui 1.0.0

package/src/components/Text/Text.contract.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Text",
+  "description": "Typography component for rendering text with consistent styling. Supports various sizes, weights, colors, and semantic elements.",
+  "category": "display",
+  "tags": [
+    "text",
+    "typography",
+    "heading",
+    "paragraph",
+    "font"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Text/index.tsx",
+  "exportName": "Text",
+  "propsSummary": [
+    "children: node (required)",
+    "as: h1|h2|h3|h4|h5|h6|p|span|label|div|strong|em|small|mark|del|ins|sub|sup|time|address|blockquote|cite|code|abbr (default: span)",
+    "variant: section-label",
+    "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl",
+    "weight: normal|medium|semibold|bold (default: \"normal\")",
+    "color: primary|secondary|tertiary|muted (default: \"primary\")",
+    "font: sans|mono (default: sans)",
+    "truncate: boolean",
+    "lineClamp: number",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Text content",
+      "required": true
+    },
+    "as": {
+      "type": "enum",
+      "description": "HTML element to render",
+      "default": "span",
+      "required": false,
+      "values": [
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "p",
+        "span",
+        "label",
+        "div",
+        "strong",
+        "em",
+        "small",
+        "mark",
+        "del",
+        "ins",
+        "sub",
+        "sup",
+        "time",
+        "address",
+        "blockquote",
+        "cite",
+        "code",
+        "abbr"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Preset text variant",
+      "required": false,
+      "values": [
+        "section-label"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Font size. 2xs (10), xs (12), sm/base (14), md (15 prose body), lg (20), xl (24), 2xl (30), 3xl (36 page title), 4xl (48 hero).",
+      "required": false,
+      "values": [
+        "2xs",
+        "xs",
+        "sm",
+        "base",
+        "md",
+        "lg",
+        "xl",
+        "2xl",
+        "3xl",
+        "4xl"
+      ]
+    },
+    "weight": {
+      "type": "enum",
+      "description": "Font weight",
+      "default": "\"normal\"",
+      "required": false,
+      "values": [
+        "normal",
+        "medium",
+        "semibold",
+        "bold"
+      ]
+    },
+    "color": {
+      "type": "enum",
+      "description": "Text color (muted is an alias for tertiary)",
+      "default": "\"primary\"",
+      "required": false,
+      "values": [
+        "primary",
+        "secondary",
+        "tertiary",
+        "muted"
+      ]
+    },
+    "font": {
+      "type": "enum",
+      "description": "Font family",
+      "default": "sans",
+      "required": false,
+      "values": [
+        "sans",
+        "mono"
+      ]
+    },
+    "truncate": {
+      "type": "boolean",
+      "description": "Truncate with ellipsis on overflow",
+      "required": false
+    },
+    "lineClamp": {
+      "type": "number",
+      "description": "Number of lines before truncating (requires truncate)",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying text with specific typography styles",
+      "Creating headings, paragraphs, or labels",
+      "Text that needs truncation or line clamping",
+      "Consistent typography across the application"
+    ],
+    "whenNot": [
+      "Complex rich text (use a rich text editor)",
+      "Code display (use CodeBlock)",
+      "Interactive text (use Link or Button)"
+    ],
+    "guidelines": [
+      "Use semantic elements (h1-h6, p) via the \"as\" prop",
+      "Maintain heading hierarchy for accessibility",
+      "Use color variants sparingly for visual hierarchy",
+      "Consider truncation for user-generated content"
+    ],
+    "accessibility": [
+      "Use proper heading levels (h1-h6) for document structure",
+      "Semantic elements convey meaning to screen readers",
+      "Truncated text should have full content in title/tooltip"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Sizes",
+      "description": "Different text sizes",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text size=\"2xs\">Extra extra small (2xs — 10px)</Text>\n  <Text size=\"xs\">Extra small (xs — 12px)</Text>\n  <Text size=\"sm\">Small (sm — 14px)</Text>\n  <Text size=\"base\">Base size (14px)</Text>\n  <Text size=\"md\">Medium prose body (md — 15px)</Text>\n  <Text size=\"lg\">Large (lg — 20px)</Text>\n  <Text size=\"xl\">Extra large (xl — 24px)</Text>\n  <Text size=\"2xl\">Extra extra large (2xl — 30px)</Text>\n  <Text size=\"3xl\">Page title (3xl — 36px)</Text>\n  <Text size=\"4xl\">Hero display (4xl — 48px)</Text>\n</div>"
+    },
+    {
+      "name": "Weights",
+      "description": "Different font weights",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text weight=\"normal\">Normal weight</Text>\n  <Text weight=\"medium\">Medium weight</Text>\n  <Text weight=\"semibold\">Semibold weight</Text>\n  <Text weight=\"bold\">Bold weight</Text>\n</div>"
+    },
+    {
+      "name": "Colors",
+      "description": "Different text colors",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text color=\"primary\">Primary color (default)</Text>\n  <Text color=\"secondary\">Secondary color</Text>\n  <Text color=\"tertiary\">Tertiary color</Text>\n  <Text color=\"muted\">Muted color (alias for tertiary)</Text>\n</div>"
+    },
+    {
+      "name": "Semantic Elements",
+      "description": "Using appropriate HTML elements",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text as=\"h1\" size=\"3xl\" weight=\"semibold\">Heading 1</Text>\n  <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Heading 2</Text>\n  <Text as=\"h3\" size=\"lg\" weight=\"semibold\">Heading 3</Text>\n  <Text as=\"p\" size=\"md\" color=\"secondary\">\n    This is a paragraph of text that demonstrates the Text component\n    with semantic paragraph element.\n  </Text>\n</div>"
+    },
+    {
+      "name": "Monospace",
+      "description": "Monospace font for code-like text",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text font=\"mono\" size=\"sm\">const greeting = \"Hello, World!\";</Text>\n  <Text font=\"mono\" size=\"sm\" color=\"secondary\">npm install @usefragments/ui</Text>\n</div>"
+    },
+    {
+      "name": "Truncation",
+      "description": "Text truncation with ellipsis",
+      "code": "<div style={{ width: '200px', display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text truncate>\n    This is a very long text that will be truncated with an ellipsis when it overflows.\n  </Text>\n  <Text truncate lineClamp={2}>\n    This text will be clamped to two lines. Any content beyond two lines\n    will be hidden and replaced with an ellipsis at the end.\n  </Text>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Link",
+      "relationship": "sibling",
+      "note": "Use Link for clickable text"
+    },
+    {
+      "component": "CodeBlock",
+      "relationship": "alternative",
+      "note": "Use CodeBlock for code display"
+    },
+    {
+      "component": "Badge",
+      "relationship": "sibling",
+      "note": "Use Badge for labels/tags"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "as: string - HTML element",
+      "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl - font size (px: 10/12/14/14/15/20/24/30/36/48)",
+      "weight: normal|medium|semibold|bold - font weight",
+      "color: primary|secondary|tertiary|muted - text color (muted = tertiary)",
+      "font: sans|mono - font family",
+      "truncate: boolean - enable truncation",
+      "lineClamp: number - max lines"
+    ],
+    "a11yRules": [
+      "A11Y_HEADING_HIERARCHY",
+      "A11Y_SEMANTIC_ELEMENTS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.045Z"
+  }
+}

package/src/components/Text/Text.module.scss

@@ -0,0 +1,136 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.text {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  color: var(--fui-text-primary, $fui-text-primary);
+  margin: 0;
+}
+
+// Variants
+.variant-section-label {
+  @include section-label-text;
+}
+
+// Font sizes
+.size-2xs {
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}
+
+.size-xs {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.size-sm {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+}
+
+.size-base {
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.size-md {
+  font-size: var(--fui-font-size-md, $fui-font-size-md);
+}
+
+.size-lg {
+  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+}
+
+.size-xl {
+  font-size: var(--fui-font-size-xl, $fui-font-size-xl);
+}
+
+.size-2xl {
+  font-size: var(--fui-font-size-2xl, $fui-font-size-2xl);
+}
+
+.size-3xl {
+  font-size: var(--fui-font-size-3xl, $fui-font-size-3xl);
+  line-height: var(--fui-line-height-display, $fui-line-height-display);
+  letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);
+}
+
+.size-4xl {
+  font-size: var(--fui-font-size-4xl, $fui-font-size-4xl);
+  line-height: var(--fui-line-height-display, $fui-line-height-display);
+  letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);
+}
+
+// Font weights
+.weight-normal {
+  font-weight: var(--fui-font-weight-normal, $fui-font-weight-normal);
+}
+
+.weight-medium {
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+}
+
+.weight-semibold {
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+}
+
+.weight-bold {
+  font-weight: var(--fui-font-weight-bold, $fui-font-weight-bold);
+}
+
+// Text colors
+.color-primary {
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
+.color-secondary {
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.color-tertiary,
+.color-muted {
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// Font family
+.mono {
+  font-family: var(--fui-font-mono, $fui-font-mono);
+}
+
+// Truncation
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// Line clamp (multi-line truncation)
+.lineClamp {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: var(--fui-line-clamp, 2);
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+// Letter-spacing presets for dense UI chrome and display numerics.
+// "tight" = labels / nav chrome, "tighter" = headings / stat values,
+// "tightest" = large display numerics.
+.tracking-normal {
+  letter-spacing: var(--fui-letter-spacing-normal, $fui-letter-spacing-normal);
+}
+
+.tracking-tight {
+  letter-spacing: var(--fui-letter-spacing-tight, $fui-letter-spacing-tight);
+}
+
+.tracking-tighter {
+  // -0.02em == the display tracking token
+  letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);
+}
+
+.tracking-tightest {
+  letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);
+}
+
+// Tabular (fixed-width) numerals — digits align in columns so updating
+// numbers don't jitter. Essential for stat values and tables.
+.tabularNums {
+  font-variant-numeric: tabular-nums;
+}

package/src/components/Text/Text.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Text } from '.';
+
+/**
+ * Text is the canonical typography primitive. Every heading, paragraph, label,
+ * and inline string in the design system routes through it for consistent size,
+ * weight, color, and font — agents should reuse it rather than styling raw
+ * `<p>`/`<span>`/`<h1>` elements by hand.
+ */
+const meta = {
+  title: 'Display/Text',
+  component: Text,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Typography component for rendering text with consistent styling and semantic elements. Prefer this over raw <p>, <span>, or heading tags.',
+      },
+    },
+  },
+  argTypes: {
+    as: {
+      control: 'select',
+      options: [
+        'h1',
+        'h2',
+        'h3',
+        'h4',
+        'h5',
+        'h6',
+        'p',
+        'span',
+        'label',
+        'div',
+        'strong',
+        'em',
+        'small',
+        'mark',
+        'del',
+        'ins',
+        'sub',
+        'sup',
+        'time',
+        'address',
+        'blockquote',
+        'cite',
+        'code',
+        'abbr',
+      ],
+      description: 'HTML element to render',
+    },
+    variant: {
+      control: 'select',
+      options: ['section-label'],
+      description: 'Preset text variant',
+    },
+    size: {
+      control: 'select',
+      options: ['2xs', 'xs', 'sm', 'base', 'md', 'lg', 'xl', '2xl', '3xl', '4xl'],
+      description: 'Font size',
+    },
+    weight: {
+      control: 'select',
+      options: ['normal', 'medium', 'semibold', 'bold'],
+      description: 'Font weight',
+    },
+    color: {
+      control: 'select',
+      options: ['primary', 'secondary', 'tertiary', 'muted'],
+      description: 'Text color (muted is an alias for tertiary)',
+    },
+    font: {
+      control: 'select',
+      options: ['sans', 'mono'],
+      description: 'Font family',
+    },
+    truncate: { control: 'boolean', description: 'Truncate with ellipsis on overflow' },
+  },
+  args: {
+    children: 'The quick brown fox jumps over the lazy dog',
+    size: 'md',
+    weight: 'normal',
+    color: 'primary',
+  },
+} satisfies Meta<typeof Text>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: 'The quick brown fox jumps over the lazy dog' },
+};
+
+export const Heading: Story = {
+  args: { as: 'h1', size: '3xl', weight: 'semibold', children: 'Page title' },
+};
+
+export const Paragraph: Story = {
+  args: {
+    as: 'p',
+    size: 'md',
+    color: 'secondary',
+    children:
+      'This is a paragraph of body text that demonstrates the Text component using a semantic paragraph element.',
+  },
+};
+
+export const SectionLabel: Story = {
+  args: { as: 'p', variant: 'section-label', children: 'On This Page' },
+};
+
+export const Bold: Story = {
+  args: { weight: 'bold', children: 'Bold weight text' },
+};
+
+export const Secondary: Story = {
+  args: { color: 'secondary', children: 'Secondary color text' },
+};
+
+export const Monospace: Story = {
+  args: { font: 'mono', size: 'sm', children: 'npm install @usefragments/ui' },
+};
+
+export const Truncated: Story = {
+  args: {
+    truncate: true,
+    style: { display: 'block', maxWidth: '200px' },
+    children:
+      'This is a very long text that will be truncated with an ellipsis when it overflows the container.',
+  },
+};

package/src/components/Text/index.tsx

@@ -0,0 +1,91 @@
+import * as React from 'react';
+import styles from './Text.module.scss';
+
+/**
+ * Typography component for rendering text with consistent styling.
+ * @see https://usefragments.com/components/text
+ */
+export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+  children: React.ReactNode;
+  /** HTML element to render.
+   * @default "span" */
+  as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label' | 'div' | 'strong' | 'em' | 'small' | 'mark' | 'del' | 'ins' | 'sub' | 'sup' | 'time' | 'address' | 'blockquote' | 'cite' | 'code' | 'abbr';
+  /** Preset text variant */
+  variant?: 'section-label';
+  /** Font size. Steps up the scale: 2xs (10), xs (12), sm/base (14), md (15 prose body),
+   * lg (20), xl (24), 2xl (30), 3xl (36 page title), 4xl (48 hero).
+   * @see https://usefragments.com/components/text#sizes */
+  size?: '2xs' | 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
+  /** Font weight.
+   * @default "normal" */
+  weight?: 'normal' | 'medium' | 'semibold' | 'bold';
+  /** Text color. `"muted"` is an alias for `"tertiary"`.
+   * @default "primary" */
+  color?: 'primary' | 'secondary' | 'tertiary' | 'muted';
+  /** Font family.
+   * @default "sans" */
+  font?: 'sans' | 'mono';
+  /** Truncate text with ellipsis when it overflows */
+  truncate?: boolean;
+  /** Number of lines before truncating (requires truncate=true) */
+  lineClamp?: number;
+  /** Letter-spacing preset. `"tight"` suits dense UI chrome labels (-0.01em);
+   * `"tighter"` suits headings and stat values (-0.02em); `"tightest"` suits
+   * display numerics (-0.025em). Omit for the font's default tracking. */
+  letterSpacing?: 'normal' | 'tight' | 'tighter' | 'tightest';
+  /** Use tabular (fixed-width) numerals so digits align in columns. Ideal for
+   * stat values, tables, timestamps, and any updating number. */
+  tabularNums?: boolean;
+}
+
+const TextRoot = React.forwardRef<HTMLElement, TextProps>(
+  function Text(
+    {
+      children,
+      as: Component = 'span',
+      variant,
+      size,
+      weight,
+      color,
+      font = 'sans',
+      truncate,
+      lineClamp,
+      letterSpacing,
+      tabularNums,
+      className,
+      style,
+      ...htmlProps
+    },
+    ref
+  ) {
+    const classes = [
+      styles.text,
+      variant && styles[`variant-${variant}`],
+      size && styles[`size-${size}`],
+      weight && styles[`weight-${weight}`],
+      color && styles[`color-${color}`],
+      font === 'mono' && styles.mono,
+      truncate && styles.truncate,
+      lineClamp && styles.lineClamp,
+      letterSpacing && styles[`tracking-${letterSpacing}`],
+      tabularNums && styles.tabularNums,
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const lineClampStyle = lineClamp
+      ? { '--fui-line-clamp': lineClamp, ...style } as React.CSSProperties
+      : style;
+
+    return (
+      <Component ref={ref as React.Ref<never>} className={classes} style={lineClampStyle} {...htmlProps}>
+        {children}
+      </Component>
+    );
+  }
+);
+
+export const Text = Object.assign(TextRoot, {
+  Root: TextRoot,
+});