@swisper.ai/design-system 0.0.2 → 0.0.4

package/src/colors.stories.tsx

@@ -1,14 +1,29 @@
 import * as React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { SearchIcon } from '@swisper.ai/icons';
+import {
+  Button,
+  EmptyState,
+  EmptyStateActionRow,
+  EmptyStateDescription,
+  EmptyStateIcon,
+  EmptyStateTitle,
+  TextField,
+  Tooltip,
+  TooltipProvider,
+  Typography,
+} from '@swisper.ai/ui';
+
 import semanticCss from '../dist/css/semantic.css?raw';
 
+import { DocsPage } from './docs/docs-section';
+
 const meta: Meta = {
   title: 'Design System/Colors',
   parameters: {
     layout: 'padded',
   },
-  tags: ['autodocs'],
 };
 
 export default meta;
@@ -44,43 +59,121 @@ function parseSemanticColors(css: string): Map<string, ColorToken[]> {
 
 const SEMANTIC_COLORS = parseSemanticColors(semanticCss);
 
+const TOKEN_COUNT = [...SEMANTIC_COLORS.values()].reduce((sum, tokens) => sum + tokens.length, 0);
+
 // Every `--st-colour-<name>` is exposed in the Tailwind theme as `--color-<name>`.
+function classOf(name: string): string {
+  return `bg-${name.replace('--st-colour-', '')}`;
+}
+
 function ColorBox({ name, value }: ColorToken) {
   const [copied, setCopied] = React.useState(false);
-  const className = `bg-${name.replace('--st-colour-', '')}`;
+  const [isOpen, setIsOpen] = React.useState(false);
+  const className = classOf(name);
 
   const copy = async () => {
     await navigator.clipboard.writeText(className);
     setCopied(true);
-    setTimeout(() => setCopied(false), 1000);
+    setIsOpen(true);
+    setTimeout(() => {
+      setCopied(false);
+      setIsOpen(false);
+    }, 1000);
   };
 
   return (
-    <button
-      type="button"
-      onClick={copy}
-      title={copied ? 'Copied!' : `${className} (${value})`}
-      aria-label={`Copy ${className}`}
-      className={`h-24 w-24 cursor-pointer rounded-full border ${copied ? 'ring-2 ring-offset-2' : ''}`}
-      style={{ backgroundColor: value }}
-    />
+    // Pressing the trigger closes a tooltip, so it is held open while it says "Copied".
+    <Tooltip
+      open={isOpen}
+      onOpenChange={(next) => setIsOpen(next || copied)}
+      tooltip={copied ? 'Copied' : `${className} · ${value}`}
+      asChild
+    >
+      <button
+        type="button"
+        onClick={copy}
+        aria-label={`Copy ${className}`}
+        className={`size-[36px] cursor-pointer rounded-full border border-divider-border-base focus-visible:outline-2 focus-visible:outline-offset-2 ${copied ? 'ring-2 ring-offset-2' : ''}`}
+        style={{ backgroundColor: value }}
+      />
+    </Tooltip>
   );
 }
 
-export const Semantic: Story = {
-  render: () => (
-    <div className="space-y-16">
-      <h1 className="text-2xl font-bold">Colors</h1>
-      {[...SEMANTIC_COLORS].map(([group, tokens]) => (
-        <section key={group} className="space-y-8">
-          <h2 className="text-lg font-semibold">{group}</h2>
-          <div className="flex flex-wrap gap-6">
-            {tokens.map((token) => (
-              <ColorBox key={token.name} {...token} />
+function ColorBrowser() {
+  const [query, setQuery] = React.useState('');
+
+  const needle = query.trim().toLowerCase();
+  const groups = [...SEMANTIC_COLORS]
+    .map(([group, tokens]) => ({
+      group,
+      tokens: tokens.filter(
+        ({ name, value }) =>
+          classOf(name).toLowerCase().includes(needle) || value.toLowerCase().includes(needle),
+      ),
+    }))
+    .filter(({ tokens }) => tokens.length > 0);
+  const matchCount = groups.reduce((sum, { tokens }) => sum + tokens.length, 0);
+
+  return (
+    <TooltipProvider>
+      <DocsPage
+        title="Colors"
+        lead="The semantic colour tokens. Search by name or value, then select a colour to copy its Tailwind class."
+      >
+        <div className="space-y-16">
+          <TextField
+            type="search"
+            size="lg"
+            aria-label="Search colors"
+            placeholder="Search by name or value"
+            startIcon={<SearchIcon />}
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+          />
+          <Typography role="status" className="text-text-secondary">
+            {needle
+              ? `${matchCount} matching ${matchCount === 1 ? 'result' : 'results'}`
+              : `${TOKEN_COUNT} colors`}
+          </Typography>
+        </div>
+
+        {groups.length === 0 ? (
+          <EmptyState>
+            <EmptyStateIcon>
+              <SearchIcon />
+            </EmptyStateIcon>
+            <EmptyStateTitle>No colors match “{query.trim()}”</EmptyStateTitle>
+            <EmptyStateDescription>
+              Check the spelling, or search for part of a name such as “feedback”.
+            </EmptyStateDescription>
+            <EmptyStateActionRow>
+              <Button variant="tertiary" onClick={() => setQuery('')}>
+                Clear search
+              </Button>
+            </EmptyStateActionRow>
+          </EmptyState>
+        ) : (
+          <div className="space-y-24">
+            {groups.map(({ group, tokens }) => (
+              <section key={group} className="space-y-12">
+                <Typography variant="title-2x-small">{group}</Typography>
+                <div className="flex flex-wrap gap-8">
+                  {tokens.map((token) => (
+                    <ColorBox key={token.name} {...token} />
+                  ))}
+                </div>
+              </section>
             ))}
           </div>
-        </section>
-      ))}
-    </div>
-  ),
+        )}
+      </DocsPage>
+    </TooltipProvider>
+  );
+}
+
+export const Default: Story = {
+  // Named after the page, so the sidebar shows one entry instead of a folder with one story.
+  name: 'Colors',
+  render: () => <ColorBrowser />,
 };

package/src/components.stories.tsx

@@ -1,5 +1,16 @@
 import * as React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  DashboardIcon,
+  DeployedCodeIcon,
+  DescriptionIcon,
+  MapIcon,
+  NewChatIcon,
+} from '@swisper.ai/icons';
+import { Typography } from '@swisper.ai/ui';
+
+import { Code, CodeBlock, DocsPage, DocsSection } from './docs/docs-section';
+import { LinkCard } from './docs/link-card';
 
 const meta: Meta = {
   title: 'Components',
@@ -12,15 +23,137 @@ const meta: Meta = {
 export default meta;
 type Story = StoryObj;
 
-export const Placeholder: Story = {
+const SECTIONS = [
+  {
+    icon: <DeployedCodeIcon />,
+    title: 'Components',
+    subtitle: '@swisper.ai/ui: buttons, forms, overlays, lists, tables and layout',
+    storyId: 'components-button--docs',
+  },
+  {
+    icon: <NewChatIcon />,
+    title: 'Chat',
+    subtitle: '@swisper.ai/web-chat-ui: messages, the composer and chat cards',
+    storyId: 'chat-overview--docs',
+  },
+  {
+    icon: <DashboardIcon />,
+    title: 'Cards',
+    subtitle: '@swisper.ai/cards-ui: card components built on ui',
+    storyId: 'cards-card--docs',
+  },
+  {
+    icon: <DescriptionIcon />,
+    title: 'Files',
+    subtitle:
+      '@swisper.ai/web-file-preview: PDF, Office, CSV, image, audio and video in the browser',
+    storyId: 'files-filepreview--docs',
+  },
+  {
+    icon: <MapIcon />,
+    title: 'Map',
+    subtitle: '@swisper.ai/web-map: MapLibre maps with selectable markers',
+    storyId: 'map-mapview--docs',
+  },
+];
+
+const INSTALL = `npm install @swisper.ai/ui`;
+
+const SETUP = `import '@swisper.ai/ui/index.css';
+
+import { Button, Tooltip, TooltipProvider } from '@swisper.ai/ui';
+import { createRoot } from 'react-dom/client';
+
+function App() {
+  return (
+    <TooltipProvider>
+      <Tooltip tooltip="Saves the draft without sending it">
+        <Button>Save draft</Button>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(<App />);`;
+
+const OWN_TAILWIND = `@import 'tw-animate-css';
+@import '@swisper.ai/design-system/src/tailwind.css';
+@source '../node_modules/@swisper.ai/ui/src';`;
+
+export const Default: Story = {
   render: () => (
-    <div className="space-y-16">
-      <h1 className="text-2xl font-bold">Components</h1>
-      <div className="space-y-8">
-        <p className="text-body">
-          This section will contain reusable UI components built on top of the foundation elements.
-        </p>
-      </div>
-    </div>
+    <DocsPage
+      title="Components"
+      lead="Accessible React components styled with the Echo tokens. The general-purpose ones are in @swisper.ai/ui; chat, cards, file preview and maps each have their own package built on it."
+    >
+      <DocsSection title="Browse">
+        <div className="grid grid-cols-1 gap-24 sm:grid-cols-2">
+          {SECTIONS.map((section) => (
+            <LinkCard key={section.storyId} {...section} />
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Install and set up">
+        <Typography>
+          Install the package, then load its stylesheet once in the app's entry file, before your
+          own CSS. React, MUI and Emotion are peer dependencies.
+        </Typography>
+        <CodeBlock>{INSTALL}</CodeBlock>
+        <Typography>
+          Wrap the app in <Code>TooltipProvider</Code> if you use tooltips, and render a component:
+        </Typography>
+        <CodeBlock>{SETUP}</CodeBlock>
+        <Typography>
+          If the app compiles its own Tailwind v4, build the Echo classes into it instead of loading{' '}
+          <Code>index.css</Code>. Install <Code>@swisper.ai/design-system</Code> and{' '}
+          <Code>tw-animate-css</Code>, then in your Tailwind entry:
+        </Typography>
+        <CodeBlock>{OWN_TAILWIND}</CodeBlock>
+        <Typography>
+          The other packages follow the same steps: install <Code>@swisper.ai/web-chat-ui</Code>,{' '}
+          <Code>cards-ui</Code>, <Code>web-file-preview</Code> or <Code>web-map</Code> next to{' '}
+          <Code>ui</Code> and load its <Code>index.css</Code> too. Each package's npm page lists its
+          peers and setup.
+        </Typography>
+      </DocsSection>
+
+      <DocsSection title="Reading a component page">
+        <Typography>Every component has the same entries in the sidebar, in this order:</Typography>
+        <ul className="list-disc space-y-8 pl-24">
+          <li>
+            <Typography asChild>
+              <span>
+                <strong>Docs</strong>: what the component is for, how its parts nest, when to use it
+                and when to pick another one, its accessibility contract and the tokens it reads.
+              </span>
+            </Typography>
+          </li>
+          <li>
+            <Typography asChild>
+              <span>
+                <strong>Default</strong>: the component as you get it with no props changed.
+              </span>
+            </Typography>
+          </li>
+          <li>
+            <Typography asChild>
+              <span>
+                <strong>Stories</strong>: one per variant, state or composition, with realistic
+                content. <strong>Examples</strong> shows the component inside the parents it is
+                meant for.
+              </span>
+            </Typography>
+          </li>
+          <li>
+            <Typography asChild>
+              <span>
+                <strong>Playground</strong>: every prop on the controls panel.
+              </span>
+            </Typography>
+          </li>
+        </ul>
+      </DocsSection>
+    </DocsPage>
   ),
 };

package/src/docs/docs-section.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react';
+
+import { Typography } from '@swisper.ai/ui';
+
+interface DocsPageProps {
+  title: string;
+  /** One or two sentences under the title that say what the page covers. */
+  lead: React.ReactNode;
+  children: React.ReactNode;
+}
+
+/** Page frame for the hand-written overview stories: title, lead, then the sections. */
+export function DocsPage({ title, lead, children }: DocsPageProps) {
+  return (
+    <div className="max-w-[960px] space-y-40">
+      <header className="space-y-8">
+        <Typography variant="title-large">{title}</Typography>
+        <Typography variant="body-large" className="text-text-secondary">
+          {lead}
+        </Typography>
+      </header>
+      {children}
+    </div>
+  );
+}
+
+interface DocsSectionProps {
+  title: string;
+  children: React.ReactNode;
+}
+
+/** One headed section of a `DocsPage`. */
+export function DocsSection({ title, children }: DocsSectionProps) {
+  return (
+    <section className="space-y-16">
+      <Typography variant="title-x-small">{title}</Typography>
+      {children}
+    </section>
+  );
+}
+
+/** Inline code: a class, token or package name inside a sentence. */
+export function Code({ children }: { children: React.ReactNode }) {
+  return (
+    <code className="rounded-[4px] bg-card-background-lvl-2 px-4 py-1 font-ibm-plex-mono text-[0.875em]">
+      {children}
+    </code>
+  );
+}
+
+/** A snippet to copy, shown as written. */
+export function CodeBlock({ children }: { children: string }) {
+  return (
+    <pre className="overflow-x-auto rounded-[8px] bg-card-background-lvl-2 p-16 font-ibm-plex-mono text-[13px] leading-[1.6]">
+      <code>{children}</code>
+    </pre>
+  );
+}

package/src/docs/link-card.tsx

@@ -8,7 +8,7 @@ interface LinkCardProps {
   icon: React.ReactNode;
   title: string;
   subtitle: string;
-  /** Storybook id of the page to open, e.g. `design-system-colors--hello-world`. */
+  /** Storybook id of the page to open, e.g. `design-system-colors--default`. */
   storyId: string;
 }
 

package/src/docs/token-scale.tsx

@@ -0,0 +1,21 @@
+export interface Token {
+  /** The part of the variable name after the prefix: `8` for `--st-spacing-8`. */
+  name: string;
+  value: string;
+}
+
+/**
+ * Reads every `<prefix><name>: <value>;` declaration from a stylesheet's text, smallest value
+ * first. A token declared more than once (one per theme) keeps its last value.
+ */
+export function parseTokens(css: string, prefix: string): Token[] {
+  const unique = new Map<string, string>();
+  const pattern = new RegExp(`${prefix}([\\w-]+):\\s*([^;]+);`, 'g');
+  for (const [, name, value] of css.matchAll(pattern)) {
+    unique.set(name, value.trim());
+  }
+
+  return [...unique]
+    .map(([name, value]) => ({ name, value }))
+    .sort((a, b) => parseFloat(a.value) - parseFloat(b.value));
+}

package/src/foundation.stories.tsx

@@ -1,27 +1,217 @@
 import * as React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DashboardIcon, FormatColorIcon, LibraryIcon } from '@swisper.ai/icons';
+import { Typography } from '@swisper.ai/ui';
+
+import semanticCss from '../dist/css/semantic.css?raw';
+
+import { Code, CodeBlock, DocsPage, DocsSection } from './docs/docs-section';
+import { LinkCard } from './docs/link-card';
+import { parseTokens } from './docs/token-scale';
+import tailwindCss from './tailwind.css?raw';
 
 const meta: Meta = {
   title: 'Design System/Foundation',
   parameters: {
     layout: 'padded',
   },
-  tags: ['autodocs'],
 };
 
 export default meta;
 type Story = StoryObj;
 
-export const Placeholder: Story = {
+// The numbered steps only: `--st-spacing-neg-*` are offsets, not part of the class scale.
+const SPACING = parseTokens(semanticCss, '--st-spacing-').filter(({ name }) => /^\d+$/.test(name));
+// The named steps; the numbered `--st-border-radius-<px>` tokens are the same values again.
+const RADII = parseTokens(semanticCss, '--st-border-radius-').filter(
+  ({ name }) => !/^\d+$/.test(name),
+);
+const BREAKPOINTS = parseTokens(tailwindCss, '--breakpoint-');
+const FONTS = parseTokens(semanticCss, '--st-font-family-')
+  .map(({ name, value }) => ({ name, family: value.replace(/^["']|["']$/g, '') }))
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+const LAYERS = [
+  {
+    prefix: '--pt-*',
+    name: 'Primitive',
+    description: 'The raw palette, dimensions and font values. Never used directly in a component.',
+  },
+  {
+    prefix: '--st-*',
+    name: 'Semantic',
+    description: 'What a value is for: a surface, a foreground, feedback, a spacing step.',
+  },
+  {
+    prefix: '--ct-*',
+    name: 'Component',
+    description:
+      'One component part in one state: the padding of a small button, the border of a hovered chip.',
+  },
+];
+
+const THEME_LIGHT = `<div data-theme="light" className="bg-layout-foreground-base">
+  <p className="text-layout-foreground-base theme-light:text-layout-foreground-inverse">
+    Readable on both surfaces
+  </p>
+</div>`;
+
+export const Default: Story = {
+  // Named after the page, so the sidebar shows one entry instead of a folder with one story.
+  name: 'Foundation',
   render: () => (
-    <div className="space-y-16">
-      <h1 className="text-2xl font-bold">Foundation</h1>
-      <div className="space-y-8">
-        <p className="text-body">
-          This section will contain foundation elements such as colors, typography, spacing, and
-          other design tokens.
-        </p>
-      </div>
-    </div>
+    <DocsPage
+      title="Foundation"
+      lead="The design tokens every Echo component is built from. They are exported from Figma, shipped by @swisper.ai/design-system as CSS variables, and exposed as Tailwind classes."
+    >
+      <DocsSection title="Token layers">
+        <Typography>
+          Tokens come in three layers, each defined by the one before it. Write Tailwind classes,
+          not the variables: <Code>bg-layout-surface-base</Code> for a semantic colour,{' '}
+          <Code>rounded-button</Code> for a component radius.
+        </Typography>
+        <div className="grid grid-cols-1 gap-16 sm:grid-cols-3">
+          {LAYERS.map((layer) => (
+            <div
+              key={layer.prefix}
+              className="space-y-8 rounded-[8px] bg-card-background-lvl-2 p-16"
+            >
+              <Typography variant="title-2x-small">{layer.name}</Typography>
+              <Code>{layer.prefix}</Code>
+              <Typography variant="body-small-high" className="text-text-secondary">
+                {layer.description}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Themes">
+        <Typography>
+          The tokens hold the dark values, and dark is the default. A light surface is marked with{' '}
+          <Code>data-theme="light"</Code>; inside it, the <Code>theme-light:</Code> variant applies
+          the classes that differ.
+        </Typography>
+        <CodeBlock>{THEME_LIGHT}</CodeBlock>
+      </DocsSection>
+
+      <DocsSection title="Spacing">
+        <Typography>
+          A number in a spacing class is pixels, not Tailwind's 4px steps: <Code>gap-8</Code> is 8px
+          and <Code>p-16</Code> is 16px. A number off this scale falls back to Tailwind's default,
+          so <Code>p-5</Code> is 20px; stay on the scale.
+        </Typography>
+        <div className="space-y-8">
+          {SPACING.map(({ name, value }) => (
+            <div key={name} className="flex items-center gap-16">
+              <Typography variant="label-sm" className="w-48 shrink-0 font-ibm-plex-mono">
+                {name}
+              </Typography>
+              <Typography variant="label-sm" className="w-48 shrink-0 text-text-secondary">
+                {value}
+              </Typography>
+              <div className="h-12 rounded-[2px] bg-brand-primary-500" style={{ width: value }} />
+            </div>
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Radius">
+        <Typography>
+          The radius scale below is what component radii are picked from. In code, use the
+          component's own class, such as <Code>rounded-button</Code>,{' '}
+          <Code>rounded-card-lvl-1</Code> or <Code>rounded-dialog</Code>, so a change in Figma
+          reaches every instance.
+        </Typography>
+        <div className="flex flex-wrap gap-24">
+          {RADII.map(({ name, value }) => (
+            <div key={name} className="flex flex-col items-center gap-8">
+              <div className="size-[72px] bg-brand-primary-500" style={{ borderRadius: value }} />
+              <Typography variant="label-sm">{name}</Typography>
+              <Typography variant="label-xs" className="text-text-secondary">
+                {value}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Breakpoints">
+        <Typography>
+          Min-width breakpoints for the responsive variants: <Code>md:grid-cols-2</Code> applies
+          from 820px up.
+        </Typography>
+        <table className="w-full max-w-[420px] border-collapse text-left">
+          <thead>
+            <tr className="border-b border-divider-border-base">
+              <th className="py-8 pr-16">
+                <Typography variant="label-sm" className="text-text-secondary">
+                  Variant
+                </Typography>
+              </th>
+              <th className="py-8">
+                <Typography variant="label-sm" className="text-text-secondary">
+                  From
+                </Typography>
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {BREAKPOINTS.map(({ name, value }) => (
+              <tr key={name} className="border-b border-divider-border-base">
+                <td className="py-8 pr-16">
+                  <Code>{name}:</Code>
+                </td>
+                <td className="py-8">
+                  <Typography variant="body-small-high">{value}</Typography>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </DocsSection>
+
+      <DocsSection title="Fonts">
+        <Typography>
+          The package names the font families but ships no font files: load them in the app. Text
+          styles are applied with the Typography component, not with font classes.
+        </Typography>
+        <div className="space-y-16">
+          {FONTS.map(({ name, family }) => (
+            <div key={name} className="flex flex-wrap items-baseline gap-x-24 gap-y-4">
+              <Typography variant="label-sm" className="w-48 shrink-0 text-text-secondary">
+                {name}
+              </Typography>
+              <span className="text-[24px]" style={{ fontFamily: `"${family}"` }}>
+                {family}
+              </span>
+            </div>
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection title="More">
+        <div className="grid grid-cols-1 gap-24 sm:grid-cols-3">
+          <LinkCard
+            icon={<FormatColorIcon />}
+            title="Colors"
+            subtitle="Every semantic color token, click to copy its class"
+            storyId="design-system-colors--default"
+          />
+          <LinkCard
+            icon={<LibraryIcon />}
+            title="Typography"
+            subtitle="Font families, weights and text variants"
+            storyId="design-system-typography--all-variants"
+          />
+          <LinkCard
+            icon={<DashboardIcon />}
+            title="Icons"
+            subtitle="Browse and search the icon set"
+            storyId="design-system-icons--default"
+          />
+        </div>
+      </DocsSection>
+    </DocsPage>
   ),
 };