UI Primitives

The SDK ships four lightweight React components that keep your element visually consistent with the Internote aesthetic. They are thin wrappers around standard HTML — opinionated enough to use the right design tokens, but simple enough not to constrain your layout.

Import from the root or from the /ui subpath:

// From the root
import { Stack, Text, Button, Icon } from '@internote/element-sdk'

// From the ui subpath (lighter import)
import { Stack, Text, Button, Icon } from '@internote/element-sdk/ui'

Stack

A flexbox container with token-based spacing. The primary layout primitive.

<Stack direction="v" gap={2}>
  <Text>Line one</Text>
  <Text>Line two</Text>
</Stack>

Convenience aliases Stack.V (vertical, the default) and Stack.H (horizontal) save a prop:

<Stack.H gap={3} alignCenter>
  <Icon name="play" />
  <Text>Play</Text>
</Stack.H>

Props

• direction ('v' | 'h'; default: 'v') — Flex direction — vertical or horizontal.
• gap (0 | 1 | 2 | 3 | 4; default: 0) — Token-based gap between children.
• center (boolean; optional) — Center both axes.
• alignCenter (boolean; optional) — Center on the cross axis only.
• justifyBetween (boolean; optional) — Space children with justify-content: space-between.

All standard div props (className, style, onClick, etc.) are forwarded.

Text

Styled text with size and font-family tokens. Renders any inline or block HTML element.

<Text as="p" size="sm" family="mono" secondary>
  Some muted monospace text
</Text>

Props

• as ('p' | 'span' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'label'; default: 'span') — HTML element to render.
• size ('sm' | 'md' | 'lg'; default: 'md') — Font size from the design token scale.
• family ('sans' | 'serif' | 'mono'; default: 'sans') — Font family token.
• secondary (boolean; optional) — Muted colour variant for labels and supporting text.

All standard HTML element props are forwarded.

Button

A styled button with variants, icon support, and an active state.

<Button variant="primary" onClick={save}>Save</Button>

<Button icon="restart" onClick={reset} />

<Button iconOnly icon="copy" active={copied} onClick={copy} />

Props

• variant ('default' | 'primary' | 'ghost'; default: 'default') — Visual style. primary is the accent-coloured action button; ghost is borderless.
• icon (BuiltinIconName | ReactElement; optional) — Icon rendered before the label.
• iconOnly (boolean; optional) — Square padding, no text visible. Use when the icon is self-explanatory.
• active (boolean; optional) — Highlighted active/pressed state.
• disabled (boolean; optional) — Standard HTML disabled behaviour.

All other <button> props are forwarded.

Icon

Renders a built-in glyph by name, or any custom SVG via the glyph prop.

<Icon name="fullscreen" />

<Icon name="play" size={20} />

<Icon glyph={<svg viewBox="0 0 24 24">...</svg>} aria-label="Custom" />

Built-in icon names

play pause restart loop next prev fullscreen exit-fullscreen copy check

Props

• name (BuiltinIconName; optional) — Render one of the built-in SVG glyphs.
• glyph (ReactElement; optional) — Custom SVG or any React element. Takes precedence over name.
• size (number | string; default: '1em') — Font size, inherits surrounding font size by default.
• aria-label (string; optional) — Accessible label. Provide one when the icon conveys meaning without surrounding text.

Putting It Together

A small control panel using all four components:

import { Stack, Text, Button, Icon } from '@internote/element-sdk'

function SimControls({ step, total, onPrev, onNext, onReset }) {
  return (
    <Stack.H gap={2} alignCenter>
      <Button icon="prev" iconOnly onClick={onPrev} disabled={step === 0} />
      <Button icon="next" iconOnly onClick={onNext} disabled={step === total - 1} />
      <Text size="sm" secondary>
        Step {step + 1} of {total}
      </Text>
      <Button variant="ghost" icon="restart" onClick={onReset}>
        Reset
      </Button>
    </Stack.H>
  )
}

Design Tokens

All four components use CSS custom properties injected by @internote/element-sdk/styles. The stylesheet is the same source as the host application's theme — your element automatically inherits light/dark mode and the user's accent colour.

Use these variables in your own CSS for a consistent look:

.my-panel {
  background: var(--bg-secondary);
  color: var(--bg-secondary-foreground);
  border: 1px solid var(--accent-5);
  border-radius: var(--radius-md);
  padding: var(--space-3);
  font-family: var(--font-family-sans);
  font-size: var(--text-sm);
}

.my-panel-highlighted {
  background: var(--accent-2);
  color: var(--accent-9-foreground);
}