@adres/mgda-ui 0.0.0-stage → 0.0.2

package/src/docs/Colors.stories.tsx

@@ -0,0 +1,192 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+
+interface Swatch {
+  className: string
+  label: string
+  token: string
+}
+
+function ColorSwatch({ className, label, token }: Swatch) {
+  return (
+    <div className="ax:flex ax:flex-col ax:gap-1.5">
+      <div className={`ax:h-16 ax:rounded-md ax:border ax:border-border ${className}`} />
+      <div className="ax:flex ax:flex-col">
+        <span className="ax:t-label-sm ax:text-foreground">{label}</span>
+        <span className="ax:t-caption ax:text-muted-foreground">{token}</span>
+      </div>
+    </div>
+  )
+}
+
+function ColorGroup({ title, swatches }: { title: string; swatches: Swatch[] }) {
+  return (
+    <section className="ax:flex ax:flex-col ax:gap-3">
+      <h2 className="ax:t-h3 ax:text-foreground-strong">{title}</h2>
+      <div className="ax:grid ax:grid-cols-2 ax:gap-4 ax:sm:grid-cols-4 ax:lg:grid-cols-7">
+        {swatches.map((swatch) => (
+          <ColorSwatch key={swatch.token} {...swatch} />
+        ))}
+      </div>
+    </section>
+  )
+}
+
+const SURFACE_SWATCHES: Swatch[] = [
+  { className: "ax:bg-background", label: "Background", token: "--background" },
+  { className: "ax:bg-foreground", label: "Foreground", token: "--foreground" },
+  { className: "ax:bg-foreground-strong", label: "Foreground strong", token: "--foreground-strong" },
+  { className: "ax:bg-foreground-muted", label: "Foreground muted", token: "--foreground-muted" },
+  { className: "ax:bg-card", label: "Card", token: "--card" },
+  { className: "ax:bg-card-foreground", label: "Card foreground", token: "--card-foreground" },
+  { className: "ax:bg-popover", label: "Popover", token: "--popover" },
+  { className: "ax:bg-popover-foreground", label: "Popover foreground", token: "--popover-foreground" },
+  { className: "ax:bg-muted", label: "Muted", token: "--muted" },
+  { className: "ax:bg-muted-foreground", label: "Muted foreground", token: "--muted-foreground" },
+  { className: "ax:bg-border", label: "Border", token: "--border" },
+  { className: "ax:bg-border-strong", label: "Border strong", token: "--border-strong" },
+  { className: "ax:bg-input", label: "Input", token: "--input" },
+  { className: "ax:bg-ring", label: "Ring", token: "--ring" },
+  { className: "ax:bg-selected", label: "Selected", token: "--selected" },
+]
+
+const SURFACE_STACK_SWATCHES: Swatch[] = [
+  { className: "ax:bg-surface-n1", label: "Surface -1", token: "--surface-n1" },
+  { className: "ax:bg-surface-0", label: "Surface 0", token: "--surface-0" },
+  { className: "ax:bg-surface-1", label: "Surface 1", token: "--surface-1" },
+  { className: "ax:bg-surface-2", label: "Surface 2", token: "--surface-2" },
+  { className: "ax:bg-surface-3", label: "Surface 3", token: "--surface-3" },
+]
+
+const PRIMARY_SWATCHES: Swatch[] = [
+  { className: "ax:bg-primary-weakest", label: "weakest", token: "--primary-weakest" },
+  { className: "ax:bg-primary-weaker", label: "weaker", token: "--primary-weaker" },
+  { className: "ax:bg-primary-weak", label: "weak", token: "--primary-weak" },
+  { className: "ax:bg-primary", label: "base", token: "--primary" },
+  { className: "ax:bg-primary-strong", label: "strong", token: "--primary-strong" },
+  { className: "ax:bg-primary-stronger", label: "stronger", token: "--primary-stronger" },
+  { className: "ax:bg-primary-strongest", label: "strongest", token: "--primary-strongest" },
+  { className: "ax:bg-primary-foreground", label: "foreground", token: "--primary-foreground" },
+]
+
+const SECONDARY_SWATCHES: Swatch[] = [
+  { className: "ax:bg-secondary-weakest", label: "weakest", token: "--secondary-weakest" },
+  { className: "ax:bg-secondary-weaker", label: "weaker", token: "--secondary-weaker" },
+  { className: "ax:bg-secondary-weak", label: "weak", token: "--secondary-weak" },
+  { className: "ax:bg-secondary", label: "base", token: "--secondary" },
+  { className: "ax:bg-secondary-strong", label: "strong", token: "--secondary-strong" },
+  { className: "ax:bg-secondary-stronger", label: "stronger", token: "--secondary-stronger" },
+  { className: "ax:bg-secondary-strongest", label: "strongest", token: "--secondary-strongest" },
+  { className: "ax:bg-secondary-foreground", label: "foreground", token: "--secondary-foreground" },
+]
+
+const ACCENT_SWATCHES: Swatch[] = [
+  { className: "ax:bg-accent-weakest", label: "weakest", token: "--accent-weakest" },
+  { className: "ax:bg-accent-weaker", label: "weaker", token: "--accent-weaker" },
+  { className: "ax:bg-accent-weak", label: "weak", token: "--accent-weak" },
+  { className: "ax:bg-accent", label: "base", token: "--accent" },
+  { className: "ax:bg-accent-strong", label: "strong", token: "--accent-strong" },
+  { className: "ax:bg-accent-stronger", label: "stronger", token: "--accent-stronger" },
+  { className: "ax:bg-accent-strongest", label: "strongest", token: "--accent-strongest" },
+  { className: "ax:bg-accent-foreground", label: "foreground", token: "--accent-foreground" },
+]
+
+const TERTIARY_SWATCHES: Swatch[] = [
+  { className: "ax:bg-tertiary-weakest", label: "weakest", token: "--tertiary-weakest" },
+  { className: "ax:bg-tertiary-weaker", label: "weaker", token: "--tertiary-weaker" },
+  { className: "ax:bg-tertiary-weak", label: "weak", token: "--tertiary-weak" },
+  { className: "ax:bg-tertiary", label: "base", token: "--tertiary" },
+  { className: "ax:bg-tertiary-strong", label: "strong", token: "--tertiary-strong" },
+  { className: "ax:bg-tertiary-stronger", label: "stronger", token: "--tertiary-stronger" },
+  { className: "ax:bg-tertiary-strongest", label: "strongest", token: "--tertiary-strongest" },
+  { className: "ax:bg-tertiary-foreground", label: "foreground", token: "--tertiary-foreground" },
+]
+
+const DESTRUCTIVE_SWATCHES: Swatch[] = [
+  { className: "ax:bg-destructive-weakest", label: "weakest", token: "--destructive-weakest" },
+  { className: "ax:bg-destructive-weaker", label: "weaker", token: "--destructive-weaker" },
+  { className: "ax:bg-destructive-weak", label: "weak", token: "--destructive-weak" },
+  { className: "ax:bg-destructive", label: "base", token: "--destructive" },
+  { className: "ax:bg-destructive-strong", label: "strong", token: "--destructive-strong" },
+  { className: "ax:bg-destructive-stronger", label: "stronger", token: "--destructive-stronger" },
+  { className: "ax:bg-destructive-strongest", label: "strongest", token: "--destructive-strongest" },
+  { className: "ax:bg-destructive-foreground", label: "foreground", token: "--destructive-foreground" },
+]
+
+const SUCCESS_SWATCHES: Swatch[] = [
+  { className: "ax:bg-success-weakest", label: "weakest", token: "--success-weakest" },
+  { className: "ax:bg-success-weaker", label: "weaker", token: "--success-weaker" },
+  { className: "ax:bg-success-weak", label: "weak", token: "--success-weak" },
+  { className: "ax:bg-success", label: "base", token: "--success" },
+  { className: "ax:bg-success-strong", label: "strong", token: "--success-strong" },
+  { className: "ax:bg-success-stronger", label: "stronger", token: "--success-stronger" },
+  { className: "ax:bg-success-strongest", label: "strongest", token: "--success-strongest" },
+  { className: "ax:bg-success-foreground", label: "foreground", token: "--success-foreground" },
+]
+
+const WARNING_SWATCHES: Swatch[] = [
+  { className: "ax:bg-warning-weakest", label: "weakest", token: "--warning-weakest" },
+  { className: "ax:bg-warning-weaker", label: "weaker", token: "--warning-weaker" },
+  { className: "ax:bg-warning-weak", label: "weak", token: "--warning-weak" },
+  { className: "ax:bg-warning", label: "base", token: "--warning" },
+  { className: "ax:bg-warning-strong", label: "strong", token: "--warning-strong" },
+  { className: "ax:bg-warning-stronger", label: "stronger", token: "--warning-stronger" },
+  { className: "ax:bg-warning-strongest", label: "strongest", token: "--warning-strongest" },
+  { className: "ax:bg-warning-foreground", label: "foreground", token: "--warning-foreground" },
+]
+
+const NEUTRAL_SWATCHES: Swatch[] = [
+  { className: "ax:bg-neutral-weakest", label: "weakest", token: "--neutral-weakest" },
+  { className: "ax:bg-neutral-weaker", label: "weaker", token: "--neutral-weaker" },
+  { className: "ax:bg-neutral-weak", label: "weak", token: "--neutral-weak" },
+  { className: "ax:bg-neutral", label: "base", token: "--neutral" },
+  { className: "ax:bg-neutral-strong", label: "strong", token: "--neutral-strong" },
+  { className: "ax:bg-neutral-stronger", label: "stronger", token: "--neutral-stronger" },
+  { className: "ax:bg-neutral-strongest", label: "strongest", token: "--neutral-strongest" },
+]
+
+const CHART_SWATCHES: Swatch[] = [
+  { className: "ax:bg-chart-1", label: "Chart 1", token: "--chart-1" },
+  { className: "ax:bg-chart-2", label: "Chart 2", token: "--chart-2" },
+  { className: "ax:bg-chart-3", label: "Chart 3", token: "--chart-3" },
+  { className: "ax:bg-chart-4", label: "Chart 4", token: "--chart-4" },
+  { className: "ax:bg-chart-5", label: "Chart 5", token: "--chart-5" },
+  { className: "ax:bg-chart-6", label: "Chart 6", token: "--chart-6" },
+  { className: "ax:bg-chart-7", label: "Chart 7", token: "--chart-7" },
+  { className: "ax:bg-chart-8", label: "Chart 8", token: "--chart-8" },
+  { className: "ax:bg-chart-9", label: "Chart 9", token: "--chart-9" },
+  { className: "ax:bg-chart-10", label: "Chart 10", token: "--chart-10" },
+]
+
+function ColorsPage() {
+  return (
+    <div className="ax:flex ax:flex-col ax:gap-10">
+      <p className="ax:t-body-md ax:text-muted-foreground">
+        Every swatch below is a semantic Tailwind utility (e.g. <code className="ax:t-code">ax:bg-primary</code>), never a
+        literal brand color. Switch the brand toolbar above to see every value repaint at runtime.
+      </p>
+      <ColorGroup title="Surfaces & structure" swatches={SURFACE_SWATCHES} />
+      <ColorGroup title="Surface stack" swatches={SURFACE_STACK_SWATCHES} />
+      <ColorGroup title="Primary" swatches={PRIMARY_SWATCHES} />
+      <ColorGroup title="Secondary" swatches={SECONDARY_SWATCHES} />
+      <ColorGroup title="Accent" swatches={ACCENT_SWATCHES} />
+      <ColorGroup title="Tertiary" swatches={TERTIARY_SWATCHES} />
+      <ColorGroup title="Destructive" swatches={DESTRUCTIVE_SWATCHES} />
+      <ColorGroup title="Success" swatches={SUCCESS_SWATCHES} />
+      <ColorGroup title="Warning" swatches={WARNING_SWATCHES} />
+      <ColorGroup title="Neutral" swatches={NEUTRAL_SWATCHES} />
+      <ColorGroup title="Chart palette" swatches={CHART_SWATCHES} />
+    </div>
+  )
+}
+
+const meta: Meta<typeof ColorsPage> = {
+  title: "Foundation/Colors",
+  component: ColorsPage,
+  parameters: { layout: "padded" },
+}
+
+export default meta
+type Story = StoryObj<typeof ColorsPage>
+
+export const Default: Story = {}

package/src/docs/GettingStarted.mdx

@@ -0,0 +1,72 @@
+import { Meta, Title, Subtitle } from "@storybook/blocks"
+
+<Meta title="Docs/Getting Started" />
+
+<Title>Getting Started</Title>
+
+<Subtitle>Install and use @adres/mgda-ui from npm</Subtitle>
+
+Packages are published publicly on [npmjs.com](https://www.npmjs.com) under the `@adres` scope. No special `.npmrc` is required.
+
+## Install
+
+```bash
+npm install @adres/mgda-ui
+```
+
+Peer dependencies (install in your app if not already present):
+
+```bash
+npm install react@19 react-dom@19 tailwindcss@4
+```
+
+## Wire CSS
+
+Import order matters with Tailwind CSS 4 and CSS-variable theming:
+
+```css
+@import "tailwindcss" prefix(ax);
+
+/* Scan the design-system source so semantic utilities are emitted */
+@source "../node_modules/@adres/mgda-ui/src";
+
+@import "@adres/mgda-ui/styles";
+```
+
+## Dark mode
+
+The MGDA theme is the default on `:root`. For dark mode: add `class="dark"` (or `data-theme="dark"`) on the same element.
+
+## Use components
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent } from "@adres/mgda-ui"
+
+export function Example() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Hello</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button variant="primary">Get started</Button>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Requirements
+
+- **Bundler:** Your app must transpile TypeScript from `node_modules` (Next.js, Vite, etc.). Package exports point at `src/`. There is no separate `dist` build yet.
+- **Tailwind 4:** Add `@source` for `@adres/mgda-ui/src` in your global CSS so component utility classes are scanned.
+- **Tokens only:** Do not hardcode colours: use semantic utilities (`ax:bg-primary`, `ax:text-foreground`, etc.).
+
+## Component stories
+
+Every component under `src/components/` has a story in Storybook under **Components**.
+
+## Links
+
+- [npm: @adres/mgda-ui](https://www.npmjs.com/package/@adres/mgda-ui)
+- Repo README: publishing and theme validation (`npm run validate:brands`)

package/src/docs/Mcp.mdx

@@ -0,0 +1,52 @@
+import { Meta, Title, Subtitle } from "@storybook/blocks"
+
+<Meta title="Docs/MCP" />
+
+<Title>DLS MCP</Title>
+
+<Subtitle>Connect @adres/dls-mcp so an AI client can use the design system</Subtitle>
+
+`@adres/dls-mcp` is the MCP server for this design system. It is a separate npm package from `@adres/mgda-ui`. Paste one config below into the client MCP settings. The key `adresx-dls` is the label the client shows.
+
+The [dls-mcp README](https://github.com/adres-dls/dls-mcp#connecting-a-client) is the source of truth if the URL or auth shape changes.
+
+## Local (stdio)
+
+Node 20 or newer. `npx` downloads the published package. No clone and no token.
+
+Cursor reads this from `.cursor/mcp.json`. Claude Code reads the same JSON from `.mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "adresx-dls": {
+      "command": "npx",
+      "args": ["-y", "@adres/dls-mcp"]
+    }
+  }
+}
+```
+
+## Hosted (HTTP)
+
+The deployed server is [https://dls-mcp.vercel.app/mcp](https://dls-mcp.vercel.app/mcp). Every request needs a bearer token. Ask a maintainer for the current value, and keep it out of the repo.
+
+```json
+{
+  "mcpServers": {
+    "adresx-dls": {
+      "url": "https://dls-mcp.vercel.app/mcp",
+      "headers": {
+        "Authorization": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+The endpoint is streamable HTTP on `POST /mcp`. When a client asks for a transport, choose `http`.
+
+## Links
+
+- [npm: @adres/dls-mcp](https://www.npmjs.com/package/@adres/dls-mcp)
+- [GitHub: adres-dls/dls-mcp](https://github.com/adres-dls/dls-mcp)

package/src/docs/Typography.stories.tsx

@@ -0,0 +1,114 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+
+interface Specimen {
+  className: string
+  label: string
+  sample?: string
+}
+
+const SAMPLE_TEXT = "The quick brown fox jumps over the lazy dog"
+
+function TypeSpecimen({ className, label, sample = SAMPLE_TEXT }: Specimen) {
+  return (
+    <div className="ax:flex ax:flex-col ax:gap-1 ax:border-b ax:border-border ax:pb-4">
+      <div className={className}>{sample}</div>
+      <span className="ax:t-caption ax:text-muted-foreground">
+        {label} - <code className="ax:t-code">{className}</code>
+      </span>
+    </div>
+  )
+}
+
+function TypeSection({ title, specimens }: { title: string; specimens: Specimen[] }) {
+  return (
+    <section className="ax:flex ax:flex-col ax:gap-4">
+      <h2 className="ax:t-h3 ax:text-foreground-strong">{title}</h2>
+      <div className="ax:flex ax:flex-col ax:gap-4">
+        {specimens.map((specimen) => (
+          <TypeSpecimen key={specimen.className} {...specimen} />
+        ))}
+      </div>
+    </section>
+  )
+}
+
+const DISPLAY_SPECIMENS: Specimen[] = [
+  { className: "ax:t-display-3xl", label: "Display 3XL" },
+  { className: "ax:t-display-2xl", label: "Display 2XL" },
+  { className: "ax:t-display-xl", label: "Display XL" },
+  { className: "ax:t-display-lg", label: "Display LG" },
+  { className: "ax:t-display-md", label: "Display MD" },
+  { className: "ax:t-display-sm", label: "Display SM" },
+]
+
+const HEADING_SPECIMENS: Specimen[] = [
+  { className: "ax:t-h1", label: "Heading 1" },
+  { className: "ax:t-h2", label: "Heading 2" },
+  { className: "ax:t-h3", label: "Heading 3" },
+  { className: "ax:t-h4", label: "Heading 4" },
+  { className: "ax:t-h5", label: "Heading 5" },
+  { className: "ax:t-h6", label: "Heading 6" },
+]
+
+const BODY_SPECIMENS: Specimen[] = [
+  { className: "ax:t-body-xl", label: "Body XL" },
+  { className: "ax:t-body-lg", label: "Body LG" },
+  { className: "ax:t-body-md", label: "Body MD" },
+  { className: "ax:t-body-sm", label: "Body SM" },
+  { className: "ax:t-body-xs", label: "Body XS" },
+]
+
+const LABEL_SPECIMENS: Specimen[] = [
+  { className: "ax:t-label-lg", label: "Label LG" },
+  { className: "ax:t-label-md", label: "Label MD" },
+  { className: "ax:t-label-sm", label: "Label SM" },
+  { className: "ax:t-label-xs", label: "Label XS" },
+  { className: "ax:t-label-2xs", label: "Label 2XS" },
+]
+
+const MISC_SPECIMENS: Specimen[] = [
+  { className: "ax:t-caption", label: "Caption" },
+  { className: "ax:t-overline", label: "Overline" },
+  { className: "ax:t-code", label: "Code", sample: "const brand = \"adres\"" },
+  { className: "ax:t-micro", label: "Micro" },
+]
+
+function TypographyPage() {
+  return (
+    <div className="ax:flex ax:flex-col ax:gap-10">
+      <p className="ax:t-body-md ax:text-muted-foreground">
+        Every specimen below is a single semantic utility class (font-size, weight, line-height, and
+        letter-spacing bundled together). Switch the brand toolbar above to see the active brand&apos;s
+        font families take effect.
+      </p>
+      <section className="ax:flex ax:flex-col ax:gap-4">
+        <h2 className="ax:t-h3 ax:text-foreground-strong">Font families</h2>
+        <div className="ax:flex ax:flex-col ax:gap-4">
+          <div className="ax:flex ax:flex-col ax:gap-1 ax:border-b ax:border-border ax:pb-4">
+            <p className="ax:font-sans ax:text-lg">{SAMPLE_TEXT}</p>
+            <span className="ax:t-caption ax:text-muted-foreground">
+              Sans - <code className="ax:t-code">font-sans</code>
+            </span>
+          </div>
+        </div>
+      </section>
+      <TypeSection title="Display" specimens={DISPLAY_SPECIMENS} />
+      <TypeSection title="Heading" specimens={HEADING_SPECIMENS} />
+      <TypeSection title="Body" specimens={BODY_SPECIMENS} />
+      <TypeSection title="Label" specimens={LABEL_SPECIMENS} />
+      <TypeSection title="Caption, overline, code & micro" specimens={MISC_SPECIMENS} />
+    </div>
+  )
+}
+
+const meta: Meta<typeof TypographyPage> = {
+  title: "Foundation/Typography",
+  component: TypographyPage,
+  parameters: { layout: "padded" },
+}
+
+export default meta
+type Story = StoryObj<typeof TypographyPage>
+
+export const Default: Story = {}

package/src/hooks/use-in-view.ts

@@ -0,0 +1,32 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+
+// Returns [ref, inView] where inView flips true once the element scrolls into view.
+// Disconnects the observer after first intersection, same semantics as whileInView once:true.
+export function useInView<T extends Element = HTMLElement>(
+  rootMargin = "-60px 0px"
+): [React.MutableRefObject<T | null>, boolean] {
+  const ref = useRef<T | null>(null)
+  const [inView, setInView] = useState(false)
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el || typeof IntersectionObserver === "undefined") return
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry?.isIntersecting) {
+          setInView(true)
+          observer.disconnect()
+        }
+      },
+      { threshold: 0.1, rootMargin }
+    )
+
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [rootMargin])
+
+  return [ref, inView]
+}

package/src/hooks/use-reduced-motion.ts

@@ -0,0 +1,26 @@
+"use client"
+
+import { useEffect, useState } from "react"
+
+/**
+ * Returns `true` when the user has requested reduced motion via the OS.
+ * Animations should fall back to instant transitions when this returns true.
+ *
+ * SSR-safe: returns `false` on the server, then re-evaluates on mount.
+ */
+export function useReducedMotion(): boolean {
+  const [prefers, setPrefers] = useState(false)
+
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return
+
+    const query = window.matchMedia("(prefers-reduced-motion: reduce)")
+    setPrefers(query.matches)
+
+    const handler = (event: MediaQueryListEvent) => setPrefers(event.matches)
+    query.addEventListener("change", handler)
+    return () => query.removeEventListener("change", handler)
+  }, [])
+
+  return prefers
+}