open-ds 0.0.0-stage → 0.1.0

package/templates/project/docs/sidebars.ts

@@ -0,0 +1,8 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+// The page order is in each page's front matter.
+const sidebars: SidebarsConfig = {
+  docs: [{ type: "autogenerated", dirName: "." }],
+};
+
+export default sidebars;

package/templates/project/docs/src/css/custom.css

@@ -0,0 +1,275 @@
+/* The docs wear the design system. build/docusaurus.css (npm run tokens) holds its tokens and
+   points Docusaurus's own variables at them. The rules below dress the parts Docusaurus has no
+   variable for in the same tokens and component keys. */
+@import url("https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&family=Bricolage+Grotesque:opsz,wght@12..96,400;12..96,600;12..96,800&family=DM+Mono:wght@400;500&family=DM+Sans:wght@400;700&family=IBM+Plex+Mono&family=IBM+Plex+Sans:wght@400;500;600&family=Inter:wght@400;600;700&family=Plus+Jakarta+Sans:wght@400;600;700&family=Poppins:wght@400;600;700&family=Source+Serif+4:wght@400;600&display=swap");
+@import "../../../build/docusaurus.css";
+
+body {
+  font-size: var(--type-body-font-size);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Headings follow the type scale, the first one included. */
+.markdown h1:first-child,
+.markdown h1 {
+  --ifm-h1-font-size: var(--type-display-font-size);
+  line-height: var(--type-display-line-height);
+  font-weight: var(--type-display-font-weight);
+}
+.markdown h2 {
+  line-height: var(--type-title-line-height);
+  font-weight: var(--type-title-font-weight);
+  margin-top: var(--space-gap-section);
+}
+.markdown h3 {
+  line-height: var(--type-heading-line-height);
+  font-weight: var(--type-heading-font-weight);
+}
+.markdown > h2 {
+  --ifm-h2-font-size: var(--type-title-font-size);
+  --ifm-h2-vertical-rhythm-top: 1;
+}
+.markdown > h3 {
+  --ifm-h3-font-size: var(--type-heading-font-size);
+  --ifm-h3-vertical-rhythm-top: 1;
+}
+
+/* Navigation: label type, control density. */
+.menu__link,
+.table-of-contents__link,
+.breadcrumbs__link,
+.navbar__link {
+  font-size: var(--type-label-font-size);
+  line-height: var(--type-label-line-height);
+  font-weight: var(--type-label-font-weight);
+}
+.menu__link--active:not(.menu__link--sublist) {
+  border-radius: var(--radius-control);
+}
+.breadcrumbs__item--active .breadcrumbs__link {
+  background: var(--color-surface-selected);
+  border-radius: var(--radius-control);
+}
+.navbar {
+  border-bottom: var(--border-width-default) solid var(--color-border-default);
+  box-shadow: none;
+}
+.footer {
+  border-top: var(--border-width-default) solid var(--color-border-default);
+}
+
+/* Tables read the table component keys. */
+.markdown table {
+  display: table;
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--table-font-size);
+}
+.markdown table thead tr {
+  background: var(--table-header-background);
+}
+.markdown table th,
+.markdown table td {
+  border: 0;
+  border-bottom: var(--border-width-default) solid var(--table-row-border);
+  padding: 0 var(--table-cell-padding-x);
+  height: var(--table-row-height);
+  text-align: left;
+}
+.markdown table th {
+  font-size: var(--type-label-font-size);
+  font-weight: var(--type-label-font-weight);
+  color: var(--color-text-secondary);
+}
+.markdown table tr:nth-child(2n) {
+  background: transparent;
+}
+
+/* Code uses the data type. */
+code {
+  font-family: var(--type-data-font-family);
+  border: var(--border-width-default) solid var(--color-border-default);
+  padding: 0 var(--space-gap-tight);
+}
+
+/* Cards, buttons, badges, tabs and callouts read their component keys. */
+.card,
+.pagination-nav__link {
+  background: var(--card-background);
+  border: var(--border-width-default) solid var(--card-border);
+  border-radius: var(--card-radius);
+  box-shadow: var(--card-shadow);
+}
+.button {
+  height: var(--button-height);
+  font-size: var(--button-font-size);
+  font-weight: var(--button-font-weight);
+  line-height: var(--button-height);
+  padding-top: 0;
+  padding-bottom: 0;
+}
+.button--primary {
+  background: var(--button-primary-background);
+  border-color: var(--button-primary-background);
+  color: var(--button-primary-label);
+}
+.button--primary:hover {
+  background: var(--button-primary-background-hover);
+}
+.button--secondary {
+  background: var(--button-secondary-background);
+  border-color: var(--button-secondary-border);
+  color: var(--button-secondary-label);
+}
+.badge {
+  font-size: var(--badge-font-size);
+  padding: 0 var(--badge-padding-x);
+  background: var(--badge-neutral-background);
+  color: var(--badge-neutral-label);
+  border: 0;
+}
+.tabs__item {
+  color: var(--tabs-label);
+  font-size: var(--type-label-font-size);
+}
+.tabs__item--active {
+  color: var(--tabs-label-active);
+  border-bottom-color: var(--tabs-indicator);
+}
+.alert,
+.theme-admonition {
+  border-radius: var(--radius-container);
+  border-width: var(--border-width-default);
+  box-shadow: none;
+}
+
+/* Specimens: small live samples on the foundation pages, drawn from the token variables. */
+.ods-specimen {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-gap-default, 0.5rem) var(--space-gap-group, 1rem);
+  padding: var(--space-inset-container, 1rem);
+  margin-bottom: var(--space-gap-section, 1.5rem);
+  border: var(--border-width-default, 1px) solid var(--color-border-default);
+  border-radius: var(--radius-container, 0.375rem);
+  background: var(--color-surface-default);
+}
+.ods-item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-gap-default, 0.5rem);
+  min-width: 13rem;
+}
+.ods-type {
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-gap-group, 1rem);
+  width: 100%;
+}
+.ods-type .ods-label {
+  flex: 0 0 5rem;
+}
+.ods-label {
+  font-family: var(--type-data-font-family, monospace);
+  font-size: var(--type-caption-font-size, 0.75rem);
+  color: var(--color-text-muted);
+}
+.ods-swatch,
+.ods-tile,
+.ods-card {
+  display: inline-block;
+  width: 1.5rem;
+  height: 1.5rem;
+  flex: none;
+  border-radius: var(--radius-control, 0.25rem);
+  border: var(--border-width-default, 1px) solid var(--color-border-default);
+}
+.ods-swatch {
+  background: var(--color-text-primary);
+}
+.ods-tile {
+  background: var(--color-surface-sunken);
+  border-color: var(--color-border-strong);
+}
+.ods-card {
+  width: 2.5rem;
+  background: var(--color-surface-raised);
+}
+.ods-bar {
+  display: inline-block;
+  height: 0.5rem;
+  min-width: 1px;
+  background: var(--color-action-primary);
+  border-radius: 1px;
+}
+.ods-line {
+  display: inline-block;
+  width: 1.5rem;
+  background: var(--color-text-primary);
+}
+.ods-font {
+  font-size: 1.125rem;
+}
+.ods-motion {
+  display: inline-block;
+  width: 3rem;
+  height: 0.75rem;
+  border-radius: 9999px;
+  background: var(--color-surface-sunken);
+  position: relative;
+}
+.ods-motion > span {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 0.75rem;
+  height: 0.75rem;
+  border-radius: 9999px;
+  background: var(--color-action-primary);
+  transition: left var(--ods-d) var(--motion-easing-standard, ease);
+}
+.ods-specimen:hover .ods-motion > span {
+  left: 2.25rem;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ods-motion > span {
+    transition: none;
+  }
+}
+.markdown table .ods-swatch,
+.markdown table .ods-tile,
+.markdown table .ods-card {
+  vertical-align: middle;
+}
+
+/* The brand: the Open DS mark in this system's colours, its name in the title type, and a tag
+   that says these are its docs. */
+.navbar__brand {
+  gap: var(--space-gap-default);
+}
+.navbar__logo {
+  height: 1.25rem;
+  margin-right: 0;
+}
+.navbar__logo img {
+  height: 100%;
+}
+.navbar__title {
+  font-family: var(--type-title-font-family);
+  font-weight: var(--type-title-font-weight);
+  font-size: var(--type-heading-font-size);
+}
+.ods-docs-tag {
+  display: inline-flex;
+  align-items: center;
+  height: 1.375rem;
+  padding: 0 var(--badge-padding-x);
+  border-radius: var(--badge-radius);
+  background: var(--color-surface-selected);
+  color: var(--color-text-link);
+  font-family: var(--type-label-font-family);
+  font-size: var(--type-caption-font-size);
+  font-weight: var(--type-label-font-weight);
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}

package/templates/project/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+build/
+storybook-static/
+docs/build/
+docs/.docusaurus/
+.DS_Store

package/templates/project/src/styles/index.css

@@ -0,0 +1,16 @@
+/* The design system's styles: Tailwind, the tokens built by Style Dictionary (npm run tokens),
+   the shadcn and Tailwind theme, and the base styles. Import this once in an app. */
+@import "tailwindcss";
+@import "../../build/tokens.css";
+@import "../../build/theme.css";
+@import "../../build/shadcn.css";
+@import "./base.css";
+
+@source "../";
+@source "../../stories";
+
+/* Portalled overlays sit on body, so body carries the scheme font too. */
+body {
+  font-family: var(--type-body-font-family);
+  color: var(--color-text-primary);
+}

package/templates/project/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+// The docs page template is MDX, loaded by Storybook.
+declare module "*.mdx" {
+  const Page: () => JSX.Element;
+  export default Page;
+}

package/templates/project/stories/docs-blocks.tsx

@@ -0,0 +1,190 @@
+// The blocks of every component's docs page. Each reads the component id and situations from the
+// stories' parameters (openDs), and this design system's scheme.json.
+import { useOf } from "@storybook/addon-docs/blocks";
+import scheme from "../scheme.json";
+import grammar from "../.open-ds/grammar.json";
+import type { Samples } from "./samples";
+
+interface SchemeData {
+  name: string;
+  inventory: {
+    in: { id: string; why: string }[];
+    out: { id: string; why: string }[];
+  };
+  samples: Samples;
+  usage: { situation: string; use: string; not: string; why: string }[];
+}
+
+type Meta = { component: string; situations: string[] };
+type Tree = Record<string, unknown>;
+
+// The component keys each built component reads.
+const KEY_GROUP: Record<string, string> = {
+  button: "button",
+  input: "input",
+  select: "input",
+  label: "input",
+  checkbox: "control",
+  switch: "control",
+  badge: "badge",
+  card: "card",
+  table: "table",
+  tabs: "tabs",
+  dialog: "overlay",
+  "dropdown-menu": "overlay",
+  toast: "overlay",
+  tooltip: "overlay",
+};
+
+/** This design system's scheme. */
+function useActiveScheme(): SchemeData {
+  return scheme as unknown as SchemeData;
+}
+
+function useOpenDs(): Meta {
+  const resolved = useOf("meta");
+  const meta = resolved.type === "meta" ? resolved.preparedMeta : undefined;
+  return (meta?.parameters?.openDs ?? {
+    component: "",
+    situations: [],
+  }) as Meta;
+}
+
+const get = (tree: unknown, path: string) =>
+  path
+    .split(".")
+    .reduce<unknown>(
+      (n, p) => (n && typeof n === "object" ? (n as Tree)[p] : undefined),
+      tree,
+    );
+
+/** The aliases a key points through, light mode, default brand. */
+function chain(s: SchemeData, path: string) {
+  const t = (s as unknown as { tokens: Tree }).tokens as {
+    primitive: Tree;
+    brands: Record<string, { theme: { base?: Tree; light: Tree } }>;
+    semantic: Tree;
+    component: Tree;
+  };
+  // Component key → semantic → the first brand's light theme pick → primitive.
+  const theme = Object.values(t.brands)[0].theme;
+  const trees = [
+    t.component,
+    t.semantic,
+    { theme: { ...theme.base, ...theme.light } },
+    t.primitive,
+  ];
+  const steps: string[] = [];
+  let at = path;
+  for (let i = 0; i < 8; i++) {
+    const node = trees
+      .map((x) => get(x, at))
+      .find((n) => n && typeof n === "object" && "$value" in (n as Tree)) as
+      | { $value: unknown }
+      | undefined;
+    const m =
+      typeof node?.$value === "string" && node.$value.match(/^\{(.+)\}$/);
+    if (!m) break;
+    steps.push(m[1]);
+    at = m[1];
+  }
+  return steps;
+}
+
+export function ComponentInfo() {
+  const { component } = useOpenDs();
+  const s = useActiveScheme();
+  const item = grammar.catalogue.items.find((i) => i.id === component);
+  const inv = s.inventory.in.find((i) => i.id === component);
+  const out = s.inventory.out.find((i) => i.id === component);
+  return (
+    <div className="sb-unstyled ods-info">
+      <p>{item?.description}</p>
+      <p>
+        <strong>
+          {inv ? "In" : "Not in"} the {s.name} inventory.
+        </strong>{" "}
+        {inv?.why ?? out?.why ?? "Its answers did not pick it."}{" "}
+        {s.inventory.in.length} of {grammar.catalogue.items.length} catalogue
+        components are in.
+      </p>
+    </div>
+  );
+}
+
+export function UsageRules() {
+  const { situations } = useOpenDs();
+  const s = useActiveScheme();
+  const titles = Object.fromEntries(
+    grammar.situations.map((x) => [x.id, x.title]),
+  );
+  const rules = s.usage.filter((u) => situations.includes(u.situation));
+  if (!rules.length) return null;
+  return (
+    <table className="ods-table">
+      <thead>
+        <tr>
+          <th>Situation</th>
+          <th>Use</th>
+          <th>Not</th>
+          <th>Why</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rules.map((r) => (
+          <tr key={r.situation}>
+            <td>{titles[r.situation]}</td>
+            <td>{r.use}</td>
+            <td>{r.not}</td>
+            <td>{r.why}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+export function ComponentKeys() {
+  const { component } = useOpenDs();
+  const s = useActiveScheme();
+  const keys = grammar.component_keys.filter(
+    (k) => k.component === KEY_GROUP[component],
+  );
+  if (!keys.length)
+    return (
+      <p>
+        From shadcn/ui. It reads shadcn&apos;s variables, which theme.css maps
+        onto the design system&apos;s semantic tokens, and the radius, shadow
+        and text scale in shadcn.css.
+      </p>
+    );
+  return (
+    <table className="ods-table">
+      <thead>
+        <tr>
+          <th>Key</th>
+          <th>What it controls</th>
+          <th>Points to</th>
+        </tr>
+      </thead>
+      <tbody>
+        {keys.map((k) => (
+          <tr key={k.id}>
+            <td>
+              <code>{k.id}</code>
+            </td>
+            <td>{k.description}</td>
+            <td>
+              {chain(s, k.id.replaceAll("/", ".")).map((x, i) => (
+                <span key={x}>
+                  {i ? " → " : ""}
+                  <code>{x}</code>
+                </span>
+              ))}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/templates/project/stories/samples.tsx

@@ -0,0 +1,102 @@
+// This design system's sample content and inventory (scheme.json). Every story shows its own words,
+// data and status meanings, and says so when the system does not carry the component.
+import type { ReactNode } from "react";
+import scheme from "../scheme.json";
+
+type Status = {
+  label: string;
+  meaning: "neutral" | "info" | "success" | "warning" | "danger";
+  why: string;
+};
+export interface Samples {
+  screen: string;
+  actions: { primary: string; secondary: string };
+  statuses: Status[];
+  table?: {
+    caption: string;
+    columns: { label: string; numeric?: boolean }[];
+    rows: { cells: string[]; status: string }[];
+  };
+  metrics: { label: string; value: string }[];
+  field: {
+    label: string;
+    placeholder: string;
+    hint: string;
+    error: string;
+    invalid: string;
+  };
+  checkbox?: string[];
+  select?: { label: string; options: string[]; value: string };
+  switches?: string[];
+  messages?: {
+    success: string;
+    error: { title: string; description: string };
+    neutral: string;
+  };
+  confirm?: {
+    trigger: string;
+    title: string;
+    body: string;
+    confirm: string;
+    cancel: string;
+  };
+  card?: {
+    title: string;
+    description: string;
+    status: string;
+    primary: string;
+    secondary: string;
+  };
+  tabs?: { label: string; content: string }[];
+  menu?: { trigger: string; items: string[]; destructive: string };
+  icon_action?: string;
+}
+const data = scheme as unknown as {
+  name: string;
+  inventory: { in: { id: string }[]; out: { id: string; why: string }[] };
+  samples: Samples;
+};
+
+/** The tone a status label maps to, from its meaning in the scheme. */
+export const toneOf = (s: Samples, label: string) =>
+  s.statuses.find((x) => x.label === label)?.meaning ?? "neutral";
+
+// The samples part each component's examples read.
+const PART: Record<string, keyof Samples> = {
+  badge: "statuses",
+  card: "card",
+  checkbox: "checkbox",
+  dialog: "confirm",
+  "dropdown-menu": "menu",
+  select: "select",
+  switch: "switches",
+  table: "table",
+  tabs: "tabs",
+  toast: "messages",
+  tooltip: "icon_action",
+};
+
+export function Show({
+  component,
+  children,
+}: {
+  component: string;
+  children: (s: Samples) => ReactNode;
+}) {
+  if (!data.inventory.in.some((i) => i.id === component)) {
+    const out = data.inventory.out.find((i) => i.id === component);
+    return (
+      <p className="max-w-xl border-l-[length:var(--border-width-focus)] border-[var(--color-border-strong)] pl-[var(--space-gap-group)] text-[var(--color-text-secondary)]">
+        {data.name} does not carry this component.{" "}
+        {out?.why ?? "It is not in its inventory."}
+      </p>
+    );
+  }
+  if (PART[component] && !data.samples[PART[component]])
+    return (
+      <p className="text-[var(--color-text-secondary)]">
+        {data.name} has no sample content for this component yet.
+      </p>
+    );
+  return <>{children(data.samples)}</>;
+}

package/templates/project/stories/usage.tsx

@@ -0,0 +1,31 @@
+// Shows this design system's when-to-use rules for the situations a component serves.
+import scheme from "../scheme.json";
+import situations from "../.open-ds/situations.json";
+
+const TITLES: Record<string, string> = Object.fromEntries(
+  situations.map((s) => [s.id, s.title]),
+);
+
+export function Usage({ situations: ids }: { situations: string[] }) {
+  const rules = scheme.usage.filter((u) => ids.includes(u.situation));
+  if (!rules.length) return null;
+  return (
+    <section className="mt-[var(--space-gap-section)] max-w-3xl border-t-[length:var(--border-width-default)] border-[var(--color-border-default)] pt-[var(--space-gap-group)]">
+      <h2 className="mb-[var(--space-gap-default)] [font-family:var(--type-heading-font-family)] text-[length:var(--type-heading-font-size)] [font-weight:var(--type-heading-font-weight)]">
+        When to use
+      </h2>
+      <dl className="grid gap-[var(--space-gap-group)]">
+        {rules.map((r) => (
+          <div key={r.situation}>
+            <dt className="[font-weight:var(--type-label-font-weight)]">
+              {TITLES[r.situation]}
+            </dt>
+            <dd className="text-[var(--color-text-secondary)]">
+              Use {r.use}. Avoid: {r.not}. {r.why}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}