@mindlogic-ai/logician-ui 3.2.0-alpha.4 → 4.0.0-alpha.10

package/src/components/Tree/TreeBranchIndentGuide.test.tsx

@@ -0,0 +1,213 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+
+import { system } from '../../theme';
+import { createTreeCollection } from './index';
+import { Tree } from './Tree';
+
+interface N {
+  id: string;
+  name: string;
+  children?: N[];
+}
+
+const sample: N = {
+  id: 'ROOT',
+  name: '',
+  children: [{ id: 'a', name: 'A', children: [{ id: 'a1', name: 'A1' }] }],
+};
+
+const collection = createTreeCollection<N>({
+  rootNode: sample,
+  nodeToValue: (n) => n.id,
+  nodeToString: (n) => n.name,
+});
+
+const renderNode = ({
+  node,
+  nodeState,
+}: {
+  node: N;
+  nodeState: { isBranch: boolean };
+}) =>
+  nodeState.isBranch ? (
+    <Tree.BranchControl>
+      <Tree.BranchText>{node.name}</Tree.BranchText>
+    </Tree.BranchControl>
+  ) : (
+    <Tree.Item>
+      <Tree.ItemText>{node.name}</Tree.ItemText>
+    </Tree.Item>
+  );
+
+function renderGuide(elbow: boolean, extraProps: { guideColor?: string } = {}) {
+  const { container } = render(
+    <ChakraProvider value={system}>
+      <Tree.Root
+        collection={collection}
+        aria-label="t"
+        defaultExpandedValue={['a']}
+      >
+        <Tree.Tree>
+          <Tree.Node
+            indentGuide={
+              elbow ? (
+                <Tree.BranchIndentGuide elbow {...extraProps} />
+              ) : (
+                <Tree.BranchIndentGuide {...extraProps} />
+              )
+            }
+            render={renderNode}
+          />
+        </Tree.Tree>
+      </Tree.Root>
+    </ChakraProvider>
+  );
+  const guide = container.querySelector<HTMLElement>(
+    '[data-part="branch-indent-guide"]'
+  );
+  if (!guide) throw new Error('no indent guide rendered');
+  return guide.className;
+}
+
+// All Chakra/emotion-injected CSS, concatenated.
+const sheetText = () =>
+  Array.from(document.querySelectorAll('style'))
+    .map((s) => s.textContent ?? '')
+    .join('\n');
+
+// The foot rule is anchored on the emotion-generated `css-*` class
+// (not the static `chakra-*` slot class), so target that one.
+const styleAnchor = (className: string) => {
+  const emotion = className
+    .trim()
+    .split(/\s+/)
+    .find((c) => /^css-/.test(c));
+  if (!emotion) throw new Error(`no emotion class in: ${className}`);
+  return '\\.' + emotion;
+};
+
+/**
+ * Regression guard for the `elbow` foot. Chakra renders ONE indent guide
+ * per `branchContent` (its first child), followed by that branch's rows
+ * as siblings — so the foot must be drawn on those sibling rows, scoped
+ * to the elbow guide's own class. An earlier `:last-of-type::after`
+ * attempt silently matched nothing (the guide is never the last sibling
+ * of its type), which is exactly what these tests pin down.
+ */
+describe('Tree.BranchIndentGuide elbow', () => {
+  it('draws a ::before foot on the guide’s sibling rows when elbow is set', () => {
+    const cls = renderGuide(true);
+    const anchor = styleAnchor(cls);
+    const css = sheetText();
+
+    // Foot rule is scoped to THIS guide's class via the sibling combinator,
+    // for both leaf rows and branch rows — never applied globally.
+    expect(css).toMatch(
+      new RegExp(`${anchor}\\s*~\\s*\\[data-part="item"\\]::before`)
+    );
+    expect(css).toMatch(
+      new RegExp(
+        `${anchor}\\s*~\\s*\\[data-part="branch"\\]\\s*>\\s*\\[data-part="branch-control"\\]::before`
+      )
+    );
+
+    // The foot paints a 1px cross-stroke pinned to the row's vertical
+    // centre, starting at the parent rail column.
+    const footRule =
+      css.match(
+        new RegExp(
+          `${anchor}\\s*~\\s*\\[data-part="item"\\]::before\\s*\\{[^}]*\\}`
+        )
+      )?.[0] ?? '';
+    expect(footRule).toContain('content:""');
+    expect(footRule).toContain('position:absolute');
+    expect(footRule).toContain('inset-block-start:50%');
+    expect(footRule).toContain('height:1px');
+    expect(footRule).toMatch(
+      /inset-inline-start:calc\(var\(--tree-offset\) - var\(--tree-elbow-indentation\)\)/
+    );
+
+    // Elbow mode widens per-level indentation: the sibling rows redefine
+    // the recipe's indentation-offset from the widened value, pushing the
+    // row text right, away from the elbow foot.
+    const rowVarsRule =
+      css.match(
+        new RegExp(`${anchor}\\s*~\\s*\\[data-part="item"\\]\\s*\\{[^}]*\\}`)
+      )?.[0] ?? '';
+    expect(rowVarsRule).toContain(
+      '--tree-elbow-indentation:calc(var(--tree-indentation) + 4px)'
+    );
+    expect(rowVarsRule).toContain(
+      '--tree-indentation-offset:calc(var(--tree-elbow-indentation) * var(--tree-depth))'
+    );
+  });
+
+  it('draws no foot for a plain guide (no elbow)', () => {
+    const cls = renderGuide(false);
+    const anchor = styleAnchor(cls);
+    // This specific guide's class must not anchor any ::before foot rule.
+    expect(sheetText()).not.toMatch(new RegExp(`${anchor}\\s*~[^{]*::before`));
+  });
+
+  it('stops the vertical segment at the centre of the last row (└)', () => {
+    const cls = renderGuide(true);
+    const anchor = styleAnchor(cls);
+    const css = sheetText();
+
+    // Middle rows: full-height vertical (├) on the row itself.
+    const middleRule =
+      css.match(
+        new RegExp(
+          `${anchor}\\s*~\\s*\\[data-part="item"\\]:not\\(:last-child\\)::after\\s*\\{[^}]*\\}`
+        )
+      )?.[0] ?? '';
+    expect(middleRule).toContain('inset-block-start:0');
+    expect(middleRule).toContain('inset-block-end:0');
+    expect(middleRule).toContain('width:1px');
+
+    // Last leaf row: segment ends at 50% so the foot forms a └.
+    const lastItemRule =
+      css.match(
+        new RegExp(
+          `${anchor}\\s*~\\s*\\[data-part="item"\\]:last-child::after\\s*\\{[^}]*\\}`
+        )
+      )?.[0] ?? '';
+    expect(lastItemRule).toContain('inset-block-start:0');
+    expect(lastItemRule).toContain('height:50%');
+
+    // Last branch row: half-height segment on its control only, so an
+    // expanded last branch has no rail running past its elbow.
+    const lastBranchRule =
+      css.match(
+        new RegExp(
+          `${anchor}\\s*~\\s*\\[data-part="branch"\\]:last-child\\s*>\\s*\\[data-part="branch-control"\\]::after\\s*\\{[^}]*\\}`
+        )
+      )?.[0] ?? '';
+    expect(lastBranchRule).toContain('height:50%');
+
+    // Non-last branch: pass-through rail spans the whole expanded subtree,
+    // painted above row hover backgrounds like the original slot rail.
+    const passThroughRule =
+      css.match(
+        new RegExp(
+          `${anchor}\\s*~\\s*\\[data-part="branch"\\]:not\\(:last-child\\)::before\\s*\\{[^}]*\\}`
+        )
+      )?.[0] ?? '';
+    expect(passThroughRule).toContain('inset-block-end:0');
+    expect(passThroughRule).toContain('z-index:1');
+  });
+
+  it('paints the guide with the custom guideColor token', () => {
+    const cls = renderGuide(true, { guideColor: 'red.500' });
+    const anchor = styleAnchor(cls);
+    const css = sheetText();
+    const footRule =
+      css.match(
+        new RegExp(
+          `${anchor}\\s*~\\s*\\[data-part="item"\\]::before\\s*\\{[^}]*\\}`
+        )
+      )?.[0] ?? '';
+    expect(footRule).toMatch(/--chakra-colors-red-500|red\.500/);
+  });
+});

package/src/components/Tree/TreeBranchIndentGuide.tsx

@@ -3,18 +3,144 @@ import { TreeView as ChakraTreeView } from '@chakra-ui/react';
 
 import { TreeBranchIndentGuideProps } from './Tree.types';
 
+// Extra per-level indentation in elbow mode. Guide-line trees read better
+// with a little more horizontal air between the elbow and the row text,
+// so each level indents this much further than the recipe default. The
+// foot length does NOT grow with it (its default is derived from the
+// original `--tree-indentation`), so the foot-to-text gap widens by the
+// same amount.
+const ELBOW_EXTRA_INDENT = '4px';
+
+// The widened per-level indentation, defined on the guide's sibling rows
+// so both the recipe's offset math and our pseudo-element math can share
+// it. Root rows (depth 1) have no guide sibling, but their offset
+// multiplies indentation by zero, so every level stays consistent.
+const ELBOW_INDENT_VARS = {
+  '--tree-elbow-indentation': `calc(var(--tree-indentation) + ${ELBOW_EXTRA_INDENT})`,
+} as const;
+
+// Re-derive the recipe's `--tree-indentation-offset` (which feeds
+// `--tree-offset`, the row's padding-start) from the widened indentation.
+// Must be set on the same elements the recipe defines it on
+// (item / branch-control) — inheritance can't override those.
+const ELBOW_OFFSET_VARS = {
+  '--tree-indentation-offset':
+    'calc(var(--tree-elbow-indentation) * var(--tree-depth))',
+} as const;
+
+// The parent rail column, measured from a child row (item / branch-control).
+// A row's content starts at its own `--tree-offset`, and the parent rail
+// sits exactly one (widened) indentation to its left (verified against the
+// recipe's offset math for both the guide and the row slots).
+const ROW_RAIL_COLUMN =
+  'calc(var(--tree-offset) - var(--tree-elbow-indentation))';
+
+// The same column, computed from the `branch` element itself. A branch
+// only carries Ark's inline `--depth` (the recipe's `--tree-offset` is
+// defined on item/branch-control, not here), so expand the recipe math:
+// rail(x) = padding + indentation * (depth - 2) + icon * 0.5 * (depth - 1)
+// — algebraically identical to ROW_RAIL_COLUMN for a row at `--depth`.
+const BRANCH_RAIL_COLUMN =
+  'calc(var(--tree-padding-inline) + var(--tree-elbow-indentation) * (var(--depth) - 2) + var(--tree-icon-size) * 0.5 * (var(--depth) - 1))';
+
 export const TreeBranchIndentGuide = forwardRef<
   HTMLDivElement,
   TreeBranchIndentGuideProps
->((props, ref) => {
-  // Chakra v3's `branchIndentGuide` slot already renders the vertical
-  // line via `position: absolute`, `width: 1px`, `bg: border`, with
-  // `insetInlineStart` auto-calculated from tree depth. Don't add
-  // `ms`/`ps` (breaks the depth math, pushes the line over content)
-  // or `borderInlineStartWidth` (stacks a second 1px stroke on top of
-  // the slot's own bg-painted 1px). Only override `bg` to lighten.
-  return (
-    <ChakraTreeView.BranchIndentGuide ref={ref} bg="border.subtle" {...props} />
-  );
-});
+>(
+  (
+    {
+      elbow = false,
+      footLength = 'calc(var(--tree-indentation) - 4px)',
+      guideColor = 'border.default',
+      ...props
+    },
+    ref
+  ) => {
+    // Chakra v3's `branchIndentGuide` slot renders ONE absolutely-positioned
+    // vertical line per `branchContent` (its first child), `height: 100%`,
+    // with `insetInlineStart` auto-calculated from tree depth. Don't add
+    // `ms`/`ps` (breaks the depth math) or `borderInlineStartWidth` (stacks
+    // a second 1px stroke on the slot's own bg-painted 1px) — only `bg`.
+    //
+    // That single full-height rail cannot form a `└` on the last row: it
+    // always paints past the last row's centre down to the content bottom.
+    // So in `elbow` mode the slot's own rail is hidden (`bg: transparent`,
+    // the element stays as the CSS sibling anchor) and the guide lines are
+    // re-drawn per row on the guide's sibling rows (`[data-part="item"]`
+    // leaves and `[data-part="branch"]` subtrees):
+    //
+    //  - every row gets a `::before` foot — the horizontal cross-stroke
+    //    from the rail column toward the row content, pinned to the row's
+    //    vertical centre;
+    //  - non-last rows get a full-height vertical segment (`├`); for a
+    //    branch it is drawn on the `[data-part="branch"]` element so it
+    //    passes through the whole expanded subtree, like the original rail
+    //    (zIndex 1 for the same paint-above-row-hover reason);
+    //  - the LAST row's segment stops at the row's vertical centre where
+    //    the foot meets it (`└`); for a branch that means half the
+    //    branch-control only, so an expanded last branch hangs below the
+    //    elbow with no rail running past it.
+    const foot = {
+      content: '""',
+      position: 'absolute',
+      insetBlockStart: '50%',
+      insetInlineStart: ROW_RAIL_COLUMN,
+      width: footLength,
+      height: '1px',
+      bg: guideColor,
+    } as const;
+    const rail = {
+      content: '""',
+      position: 'absolute',
+      insetBlockStart: '0',
+      insetInlineStart: ROW_RAIL_COLUMN,
+      width: '1px',
+      bg: guideColor,
+    } as const;
+    const elbowCss = elbow
+      ? {
+          '& ~ [data-part="item"]': {
+            ...ELBOW_INDENT_VARS,
+            ...ELBOW_OFFSET_VARS,
+          },
+          // branch-control reads --tree-elbow-indentation by inheritance,
+          // but the offset override must sit on the control itself.
+          '& ~ [data-part="branch"]': ELBOW_INDENT_VARS,
+          '& ~ [data-part="branch"] > [data-part="branch-control"]':
+            ELBOW_OFFSET_VARS,
+          '& ~ [data-part="item"]::before': foot,
+          '& ~ [data-part="branch"] > [data-part="branch-control"]::before':
+            foot,
+          '& ~ [data-part="item"]:not(:last-child)::after': {
+            ...rail,
+            insetBlockEnd: '0',
+          },
+          '& ~ [data-part="item"]:last-child::after': {
+            ...rail,
+            height: '50%',
+          },
+          '& ~ [data-part="branch"]:not(:last-child)::before': {
+            ...rail,
+            insetBlockEnd: '0',
+            insetInlineStart: BRANCH_RAIL_COLUMN,
+            zIndex: 1,
+          },
+          '& ~ [data-part="branch"]:last-child > [data-part="branch-control"]::after':
+            {
+              ...rail,
+              height: '50%',
+            },
+        }
+      : undefined;
+
+    return (
+      <ChakraTreeView.BranchIndentGuide
+        ref={ref}
+        bg={elbow ? 'transparent' : guideColor}
+        css={elbowCss}
+        {...props}
+      />
+    );
+  }
+);
 TreeBranchIndentGuide.displayName = 'TreeBranchIndentGuide';

package/src/components/Typography/Link.tsx

@@ -23,7 +23,11 @@ export const Link = forwardRef<HTMLAnchorElement, LinkCustomProps>(
     return (
       <ChakraLink
         ref={ref}
-        fontWeight="semibold"
+        // Inherit the surrounding text weight so an inline link reads as part of
+        // its sentence (extrabold inside an H1, body weight inside a paragraph)
+        // rather than a fixed-semibold patch. Color + underline carry the link
+        // affordance. Override with an explicit `fontWeight` when needed.
+        fontWeight="inherit"
         wordBreak="keep-all"
         color={linkColor}
         _hover={{

package/src/index.ts

@@ -53,7 +53,6 @@ export * from './components/LogicianProvider';
 export * from './components/Markdown';
 export * from './components/Masonry';
 export * from './components/MaxLengthIndicator';
-export * from './components/MDXEditor';
 export * from './components/Menu';
 export * from './components/Modal';
 export * from './components/MonthPicker';

package/src/theme/Surfaces.stories.tsx

@@ -0,0 +1,208 @@
+import { Box, Grid, HStack, Stack, VStack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import { InlineCode } from '../components/InlineCode';
+import { SegmentedControl } from '../components/SegmentedControl';
+import {
+  ProgressSegment,
+  SegmentedProgressBar,
+} from '../components/SegmentedProgressBar';
+import {
+  Slider,
+  SliderControl,
+  SliderFilledTrack,
+  SliderThumb,
+  SliderTrack,
+} from '../components/Slider';
+import { Spinner } from '../components/Spinner';
+import { Switch } from '../components/Switch';
+import { H4, Subtext, Text } from '../components/Typography';
+
+/**
+ * # Surfaces & contrast
+ *
+ * Page-like compositions for eyeballing whether components keep enough contrast
+ * on each of the three main page-background tokens. Flip the **Color mode**
+ * toolbar control to check both light and dark.
+ *
+ * The page tokens resolve to:
+ * | token | light | role |
+ * | --- | --- | --- |
+ * | `bg.surface` | `white` | cards / elevated surfaces |
+ * | `bg.sunken` | `gray.50` | primary page wash for list / overview pages |
+ * | `bg.canvas` | `gray.0` | navigation chrome |
+ *
+ * The trap: several component fills also live in the lightest grays — `bg.subtle`
+ * is `gray.50` (**identical to `bg.sunken`**) and `bg.muted` is `gray.100`
+ * (~1.03:1 against `bg.sunken`). A component that paints a resting surface with
+ * those tokens reads fine on a `bg.surface` card but loses its bounds on a
+ * `bg.sunken` page. These stories exist to catch exactly that — a control should
+ * still read as a bounded control on all three surfaces, in both modes.
+ */
+const meta = {
+  title: 'Theme/Surfaces',
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+const SEGMENT_OPTIONS = [
+  { label: 'Day', value: 'day' },
+  { label: 'Week', value: 'week' },
+  { label: 'Month', value: 'month' },
+];
+
+const PAGE_SURFACES = ['bg.surface', 'bg.sunken', 'bg.canvas'] as const;
+
+/**
+ * The full set of at-risk components rendered once per page-background token.
+ * Scan each column top to bottom: every control should have a visible edge or
+ * fill on every surface. Anything that melts into the background on `bg.sunken`
+ * (the middle column in light mode) is the bug this story is here to surface.
+ */
+const SurfaceShowcase = () => {
+  const [segment, setSegment] = useState('week');
+  const [sliderValue, setSliderValue] = useState([40]);
+
+  return (
+    <Grid templateColumns={`repeat(${PAGE_SURFACES.length}, 1fr)`} gap={0}>
+      {PAGE_SURFACES.map((surface) => (
+        <VStack
+          key={surface}
+          bg={surface}
+          p={8}
+          gap={6}
+          align="stretch"
+          minH="100vh"
+        >
+          <Box>
+            <H4>on {surface}</H4>
+            <Subtext>
+              {surface === 'bg.sunken'
+                ? 'the page-wash case where bg.subtle / bg.muted fills collide'
+                : surface === 'bg.surface'
+                  ? 'the elevated-card baseline'
+                  : 'navigation-chrome surface'}
+            </Subtext>
+          </Box>
+
+          <VStack align="stretch" gap={2}>
+            <Subtext>SegmentedControl (outline: border.default)</Subtext>
+            <SegmentedControl
+              options={SEGMENT_OPTIONS}
+              value={segment}
+              onSelect={setSegment}
+              size="sm"
+            />
+          </VStack>
+
+          <VStack align="stretch" gap={2}>
+            <Subtext>InlineCode (outline: border.default)</Subtext>
+            <Text>
+              Run <InlineCode>yarn build</InlineCode> to compile.
+            </Text>
+          </VStack>
+
+          <VStack align="stretch" gap={2}>
+            <Subtext>Switch — off-state track (fill: bg.track)</Subtext>
+            <HStack gap={4}>
+              <Switch size="md">
+                <Switch.Control />
+              </Switch>
+              <Switch size="md" defaultChecked>
+                <Switch.Control />
+              </Switch>
+            </HStack>
+          </VStack>
+
+          <VStack align="stretch" gap={2}>
+            <Subtext>Slider — empty rail (fill: bg.track)</Subtext>
+            <Slider
+              value={sliderValue}
+              min={0}
+              max={100}
+              onValueChange={(details) => setSliderValue(details.value)}
+            >
+              <SliderControl>
+                <SliderTrack>
+                  <SliderFilledTrack />
+                </SliderTrack>
+                <SliderThumb index={0} />
+              </SliderControl>
+            </Slider>
+          </VStack>
+
+          <VStack align="stretch" gap={2}>
+            <Subtext>SegmentedProgressBar — empty portion (fill: bg.track)</Subtext>
+            <SegmentedProgressBar max={100}>
+              <ProgressSegment value={45} filledTrackColor="primary.main" />
+            </SegmentedProgressBar>
+          </VStack>
+
+          <VStack align="start" gap={2}>
+            <Subtext>Spinner — track (bg.track)</Subtext>
+            <Spinner />
+          </VStack>
+        </VStack>
+      ))}
+    </Grid>
+  );
+};
+
+/**
+ * Side-by-side reference: all at-risk components on `bg.surface`, `bg.sunken`,
+ * and `bg.canvas` at once. In light mode, watch the middle (`bg.sunken`) column
+ * — every control should still read as a bounded control there. Structured
+ * controls (`SegmentedControl`, `InlineCode`) are outlined (`border.default`);
+ * meter surfaces (`Switch`, `Slider`, `SegmentedProgressBar`,
+ * `Spinner`) use the `bg.track` fill so the track reads on the page wash.
+ */
+export const ContrastOnPageBackgrounds: Story = {
+  render: () => <SurfaceShowcase />,
+};
+
+/**
+ * A realistic `bg.sunken` overview page (the most common offender surface): a
+ * filter bar of `SegmentedControl`s and inline-code chips sitting directly on
+ * the page wash, with no intervening card. This is what an end user actually
+ * sees on a list/index page.
+ */
+export const SunkenOverviewPage: Story = {
+  render: () => {
+    const [range, setRange] = useState('week');
+    const [view, setView] = useState('list');
+    return (
+      <Box bg="bg.sunken" minH="100vh" p={8}>
+        <Stack gap={6} maxW="720px">
+          <H4>Usage overview</H4>
+          <HStack gap={4} wrap="wrap">
+            <SegmentedControl
+              options={SEGMENT_OPTIONS}
+              value={range}
+              onSelect={setRange}
+              size="sm"
+            />
+            <SegmentedControl
+              options={[
+                { label: 'List', value: 'list' },
+                { label: 'Grid', value: 'grid' },
+              ]}
+              value={view}
+              onSelect={setView}
+              size="sm"
+            />
+          </HStack>
+          <Text>
+            Filtered by <InlineCode>status:active</InlineCode> over the selected
+            range.
+          </Text>
+        </Stack>
+      </Box>
+    );
+  },
+};

package/src/theme/colors.ts

@@ -403,6 +403,18 @@ export const semanticTokens = {
       sunken: {
         value: { base: '{colors.gray.50}', _dark: desaturatedGray[1500] },
       },
+      // Recessed control-track surface for "meter"-style components whose
+      // unfilled track carries meaning (Switch off-state, Slider rail,
+      // SegmentedProgressBar remainder, Spinner track). Unlike `bg.subtle` /
+      // `bg.muted` (gray.50 / gray.100), which collapse into the `bg.sunken`
+      // page wash in light mode, this sits at gray.300 so the track reads as a
+      // filled surface on any background. Dark keeps the `bg.muted` value
+      // (desaturatedGray[1200]) — already lighter than the dark canvas/surface,
+      // so it reads there without change. Use this only for control tracks, not
+      // as a general fill (that stays `bg.subtle` / `bg.muted`).
+      track: {
+        value: { base: '{colors.gray.300}', _dark: desaturatedGray[1200] },
+      },
       // Override Chakra's default `bg.panel` (whose `_dark` resolves to Chakra's
       // own gray.950 = #111111, off our slate palette). Light value is white —
       // identical to Chakra's default — so this only realigns dark overlay
@@ -530,6 +542,7 @@ export type SemanticColorToken =
       | 'subtle'
       | 'muted'
       | 'sunken'
+      | 'track'
       | 'inverse'
       | 'selected'
       | 'highlighted'}`

package/src/theme/global.ts

@@ -26,7 +26,10 @@ export const globalCss = defineGlobalStyles({
 
   html: {
     height: 'var(--chakra-vh)',
-    fontSize: 16,
+    // Global base font size. The whole type/spacing scale is em-relative, so
+    // this single value drives the app-wide baseline; surfaces that need a
+    // different base (e.g. FactChat chat at 16px) opt in via <ScaledContext>.
+    fontSize: 14,
     fontFamily: [
       pretendard.style.fontFamily,
       inter.style.fontFamily,

package/src/theme/index.ts

@@ -18,21 +18,25 @@ const SHARED_TEXT_STYLE_VALUES = {
   h1: {
     fontFamily: 'heading',
     fontSize: { base: '2.4em', md: '3em' }, // 38.4px → 48px
-    fontWeight: 'bold',
+    // Display sizes carry the heaviest weight; the tight negative tracking
+    // above keeps extrabold from reading loose at 48px.
+    fontWeight: 'extrabold',
     lineHeight: '1.33',
     letterSpacing: '-0.02em',
   },
   h2: {
     fontFamily: 'heading',
     fontSize: { base: '2em', md: '2.5em' }, // 32px → 40px
-    fontWeight: 'semibold',
+    fontWeight: 'extrabold',
     lineHeight: '1.33',
     letterSpacing: '-0.01em',
   },
   h3: {
     fontFamily: 'heading',
     fontSize: { base: '1.5em', md: '1.75em' }, // 24px → 28px
-    fontWeight: 'semibold',
+    // Steps down to bold — the weight ramp tapers as size shrinks so heavy
+    // display weights don't muddy the smaller headings (h4/h5 stay lighter).
+    fontWeight: 'bold',
     lineHeight: '1.33',
     letterSpacing: '-0.01em',
   },
@@ -74,7 +78,7 @@ const SHARED_TEXT_STYLE_VALUES = {
  * Text styles for consistent typography across the application
  * Names match fontSize tokens for easy migration: fontStyle="h1" → textStyle="h1"
  *
- * Base font size: 16px (set in global.ts)
+ * Base font size: 14px (set in global.ts)
  * Responsive scaling using em units (relative to nearest ancestor font-size):
  * - Mobile (base): Slightly smaller for better readability on small screens
  * - Desktop (md+): Original design sizes