@mindlogic-ai/logician-ui 5.0.0-alpha.1 → 5.0.0-alpha.3

package/src/guidelines/_components/Lang.tsx

@@ -0,0 +1,175 @@
+/**
+ * Doc-only language switch for the Storybook guideline pages.
+ *
+ * One MDX file carries both languages: wrap each block in `<En>` / `<Ko>` and
+ * put `<LangToggle />` at the top of the page. The choice is kept in
+ * localStorage (default English) and every block on the page — and on every
+ * other guideline page — follows it.
+ *
+ * Not part of the published library: nothing in `src/index.ts` imports it,
+ * `check-component-exports.js` only scans `src/components`, and the rollup
+ * build excludes `src/guidelines/**`.
+ */
+import { ReactNode, useSyncExternalStore } from 'react';
+
+type DocLang = 'en' | 'ko';
+
+const STORAGE_KEY = 'logician-ui:docs-lang';
+const listeners = new Set<() => void>();
+let current: DocLang | undefined;
+
+const read = (): DocLang => {
+  try {
+    return window.localStorage.getItem(STORAGE_KEY) === 'ko' ? 'ko' : 'en';
+  } catch {
+    return 'en';
+  }
+};
+
+const write = (lang: DocLang) => {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, lang);
+  } catch {
+    // Storage blocked (private mode): the switch still works for this page.
+  }
+  current = lang;
+  listeners.forEach((notify) => notify());
+};
+
+const snapshot = (): DocLang => (current ??= read());
+
+// Another tab changed it: one listener for the whole page, not one per block.
+const onStorage = (event: StorageEvent) => {
+  if (event.key !== STORAGE_KEY) return;
+  current = read();
+  listeners.forEach((notify) => notify());
+};
+
+const subscribe = (notify: () => void) => {
+  if (listeners.size === 0) window.addEventListener('storage', onStorage);
+  listeners.add(notify);
+  return () => {
+    listeners.delete(notify);
+    if (listeners.size === 0) window.removeEventListener('storage', onStorage);
+  };
+};
+
+/** The language the reader picked; `'en'` until they pick one. */
+const useDocLang = (): DocLang =>
+  useSyncExternalStore(subscribe, snapshot, () => 'en');
+
+const pick = <V,>(lang: DocLang, en: V, ko: V) => (lang === 'ko' ? ko : en);
+
+const Block = ({ lang, children }: { lang: DocLang; children: ReactNode }) =>
+  useDocLang() === lang ? <div lang={lang}>{children}</div> : null;
+
+/** English block. Leave a blank line after the opening tag so Markdown parses. */
+export const En = ({ children }: { children: ReactNode }) => (
+  <Block lang="en">{children}</Block>
+);
+
+/** Korean block. Leave a blank line after the opening tag so Markdown parses. */
+export const Ko = ({ children }: { children: ReactNode }) => (
+  <Block lang="ko">{children}</Block>
+);
+
+/** Inline text in the reader's language, for captions and table cells. */
+export const T = ({ en, ko }: { en: ReactNode; ko: ReactNode }) => {
+  const lang = useDocLang();
+  return <span lang={lang}>{pick(lang, en, ko)}</span>;
+};
+
+const OPTIONS: { value: DocLang; label: string }[] = [
+  { value: 'en', label: 'English' },
+  { value: 'ko', label: '한국어' },
+];
+
+/** Top-of-page switch. Renders as a two-button segmented control. */
+export const LangToggle = () => {
+  const lang = useDocLang();
+  return (
+    <div
+      role="group"
+      aria-label="Language / 언어"
+      style={{
+        display: 'inline-flex',
+        border: '1px solid #D8D2CA',
+        borderRadius: 8,
+        overflow: 'hidden',
+        margin: '0 0 16px',
+        fontSize: 13,
+      }}
+    >
+      {OPTIONS.map((option) => {
+        const active = option.value === lang;
+        return (
+          <button
+            key={option.value}
+            type="button"
+            lang={option.value}
+            aria-pressed={active}
+            onClick={() => write(option.value)}
+            style={{
+              padding: '6px 14px',
+              border: 0,
+              cursor: 'pointer',
+              fontWeight: active ? 700 : 400,
+              background: active ? '#252525' : 'transparent',
+              color: active ? '#F5EDE0' : '#252525',
+            }}
+          >
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+};
+
+const VERDICT = {
+  do: {
+    mark: '✓',
+    en: 'Do',
+    ko: '이렇게 하세요',
+    rule: '#5E7A37',
+    ink: '#425C17',
+  },
+  dont: {
+    mark: '×',
+    en: "Don't",
+    ko: '이렇게 하지 마세요',
+    rule: '#A02525',
+    ink: '#A02525',
+  },
+};
+
+/** Do / Don't caption under a `<Canvas>` specimen. */
+export const Verdict = ({
+  kind,
+  en,
+  ko,
+}: {
+  kind: 'do' | 'dont';
+  en: ReactNode;
+  ko: ReactNode;
+}) => {
+  const lang = useDocLang();
+  const v = VERDICT[kind];
+  return (
+    <p
+      lang={lang}
+      style={{
+        margin: '-12px 0 28px',
+        paddingLeft: 12,
+        borderLeft: `3px solid ${v.rule}`,
+        fontSize: 14,
+        lineHeight: 1.6,
+      }}
+    >
+      <strong style={{ color: v.ink }}>
+        {v.mark} {pick(lang, v.en, v.ko)}.
+      </strong>{' '}
+      {pick(lang, en, ko)}
+    </p>
+  );
+};

package/src/guidelines/_components/TokenTable.tsx

@@ -0,0 +1,136 @@
+/**
+ * Doc-only token table for guideline pages: one row per semantic token, with
+ * its light and dark value resolved from the shipped theme
+ * (`getSwatchGroups` in `src/theme/paletteSwatches.ts`). No hex is written by
+ * hand, so a palette change shows up here on the next build.
+ *
+ * Render it inside a story (it uses Chakra), then pull the story into MDX with
+ * `<Canvas of={…} />` or `<Story of={…} />`. Not exported from the library.
+ */
+import type { ReactNode } from 'react';
+import { Box, Grid } from '@chakra-ui/react';
+import { readableColor } from 'polished';
+
+import { getSwatchGroups, Swatch } from '../../theme/paletteSwatches';
+import { T } from './Lang';
+
+const SWATCHES: ReadonlyMap<string, Swatch> = new Map(
+  getSwatchGroups().flatMap(([, swatches]) =>
+    swatches.map((swatch) => [swatch.path, swatch] as const)
+  )
+);
+
+/** Light and dark hex of a public semantic token. Throws on an unknown name. */
+const resolveToken = (path: string): Swatch => {
+  const swatch = SWATCHES.get(path);
+  if (!swatch) throw new Error(`Unknown semantic colour token: ${path}`);
+  return swatch;
+};
+
+/** Label colour for a chip: brand black or white, whichever reads on it. */
+const labelOn = (hex: string) =>
+  readableColor(hex, '#252525', '#FFFFFF', false);
+
+const Chip = ({ hex }: { hex: string }) => {
+  const transparent = !/^#/.test(hex);
+  return (
+    <Box
+      // Literal values, not tokens: the chip shows one fixed mode's value
+      // whatever mode the page is in.
+      style={{
+        background: transparent ? undefined : hex,
+        color: transparent ? undefined : labelOn(hex),
+      }}
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderStyle={transparent ? 'dashed' : 'solid'}
+      borderRadius="sm"
+      px={2}
+      py={1.5}
+      fontFamily="mono"
+      fontSize="11px"
+      minW="88px"
+    >
+      {hex.replace('#', '')}
+    </Box>
+  );
+};
+
+type TokenRow = {
+  /** Semantic token path, e.g. `primary.main`. */
+  token: string;
+  /** What the token is for, in the reader's language. */
+  use?: ReactNode;
+};
+
+const HEADERS: ReactNode[] = [
+  <T key="token" en="Token" ko="토큰" />,
+  <T key="light" en="Light" ko="라이트" />,
+  <T key="dark" en="Dark" ko="다크" />,
+  <T key="use" en="Use" ko="쓰는 곳" />,
+];
+
+/**
+ * Token | light | dark | use. Pass `rows` as token names or `{ token, use }`;
+ * `use` is usually a `<T en ko />` so it follows the page language.
+ */
+export const TokenTable = ({ rows }: { rows: (string | TokenRow)[] }) => {
+  const normalised = rows.map((row) =>
+    typeof row === 'string' ? { token: row } : row
+  );
+  const hasUse = normalised.some((row) => row.use);
+  return (
+    <Grid
+      templateColumns={{
+        base: 'minmax(0,1fr) auto auto',
+        md: hasUse
+          ? 'minmax(160px,auto) auto auto minmax(0,1fr)'
+          : 'minmax(160px,auto) auto auto',
+      }}
+      columnGap={3}
+      rowGap={1.5}
+      alignItems="center"
+      justifyContent="start"
+      fontSize="13px"
+      color="fg.default"
+      maxW="100%"
+    >
+      {HEADERS.slice(0, hasUse ? 4 : 3).map((header, i) => (
+        <Box
+          key={i}
+          fontWeight="bold"
+          color="fg.subtle"
+          display={i === 3 ? { base: 'none', md: 'block' } : undefined}
+        >
+          {header}
+        </Box>
+      ))}
+      {normalised.map(({ token, use }) => {
+        const { light, dark } = resolveToken(token);
+        return (
+          <Box key={token} display="contents">
+            <Box fontFamily="mono" fontSize="12px" wordBreak="break-all">
+              {token}
+              {use && (
+                <Box
+                  display={{ base: 'block', md: 'none' }}
+                  fontFamily="body"
+                  color="fg.subtle"
+                >
+                  {use}
+                </Box>
+              )}
+            </Box>
+            <Chip hex={light} />
+            <Chip hex={dark} />
+            {hasUse && (
+              <Box display={{ base: 'none', md: 'block' }} color="fg.muted">
+                {use}
+              </Box>
+            )}
+          </Box>
+        );
+      })}
+    </Grid>
+  );
+};

package/src/theme/SemanticTokens.mdx

@@ -50,6 +50,32 @@ Emphasis is weight, not colour: headings use `fg.default`, never `primary.*`.
 Status colours mean status — don't borrow `success`/`warning` for decoration;
 that is what `category.*` is for.
 
+## Blue means data and links
+
+Blue is the one hue BAZE gives a meaning outside status: **data and links**.
+Use it for both, and for nothing decorative.
+
+- **Links** — `fg.link` / `fg.linkHover` (blue ink, #48607A / #AFC7E1), in chat
+  messages, markdown and app copy alike. Never ink-black or coral for a link.
+- **Data visualisation** — usage/share bars, single-measure bar and line charts,
+  maps, heatmaps, progress-by-share: a **blue monochrome ramp**, never a
+  rainbow and never a grey ramp. Steps differ in lightness only (the saturated
+  `blue.base` is left out); the largest value gets the strongest step.
+
+| Step | Light | Dark |
+| --- | --- | --- |
+| 1 (largest) | `#48607A` (`blue.ink`) · white label | `#AFC7E1` (`blue.inkDark`) · ink label |
+| 2 | `#7492B3` · ink label | `#7492B3` · ink label |
+| 3 | `#AFC7E1` · ink label | `#48607A` · white label |
+| 4 | `#DFEBF9` (`blue.surface`) · ink label | `#232F3D` (`blue.surfaceDark`) · white label |
+
+Pick each label by measured contrast (≥ 4.5:1), not by step number.
+A chart that must tell several *categories* apart (multi-series lines) keeps
+`CHART_SERIES_HUES` in `LineGraph/seriesColors.ts`, which leaves blue out so
+no series reads as a link or an info state.
+`info` is also blue; status always comes with an icon and words, so a blue
+chart is never mistaken for an info notice.
+
 ## Modes
 
 Every role flips with the colour mode (`_light` / `_dark`) and has a

package/src/theme/claude.md

@@ -249,6 +249,9 @@ follow the scheme and high contrast. Base font size is 14px.
 4. Beige (`secondary.surface*`) is for small surfaces (bubbles, soft
    badges/tags, the modal header band), never rows or panels.
 5. Disabled = `disabled.*`, not opacity. Focus = `focusRing`.
+6. Blue means data and links: links are `fg.link`; data visualisation
+   (usage bars, single-measure charts, maps) is a blue monochrome ramp, never a
+   rainbow or grey ramp. Values: SemanticTokens.mdx → "Blue means data and links".
 
 ## Extending the Theme