@ossy/design-system

React component library for the Ossy ecosystem — themable UI primitives, layout, forms, and shell extension hooks. Built for React 19+ with server-side rendering and CSS-variable theming from @ossy/themes.

This package is not a home for product-specific or marketing widgets. Domain UI lives in feature packages (for example @ossy/profile, @ossy/resumes, @ossy/booking).

What’s in the box

| Area | Examples | |------|----------| | Primitives | Button, Text, Title, Input, Card, Alert, Badge, Tabs, … | | Layout | View, View.Item, Page, PageSection | | Forms | Form, Fields, applyFieldChange, field slot keys | | Theme | Theme, useTheme (requires @ossy/themes) | | Shell extension | ComponentSlotsProvider, Slot, useSlot | | Icons | Icon — kebab-case names, lazy css.gg chunks |

See docs/SLOTS.md for the three different “slot” concepts and AUDIT.md for refactor history and open work.

Four-layer mental model

Use this stack when deciding which API to reach for:

1. Tokens & theme — Install @ossy/themes, wrap the app in Theme, switch palettes with useTheme. Components read var(--*) tokens only at the global level.
2. Layout primitives — View (and optionally Page / PageSection) for structure. Layout slots are the slot attribute on children (header, content, sidebar-primary, …).
3. Shell & form extension — Component slots: app export const slots in *.layout.jsx + <Slot />; resource/input via metadata.id on *.component.jsx. Form field slots: input:* via formFieldSlotKey.
4. Components — Buttons, inputs, feedback, display, navigation helpers.

Rule of thumb: layout regions ≠ injectable shell components ≠ form field overrides.

Installation

npm install @ossy/design-system @ossy/themes

Peer dependencies

• react >= 19.0.0
• react-dom >= 19.0.0
• @ossy/themes — theme objects passed to Theme
• markdown-to-jsx, react-syntax-highlighter — only if you use MarkdownViewer

Quick start

import { Theme } from '@ossy/design-system'
import { CloudLight } from '@ossy/themes'

export default function App() {
  return (
    <Theme theme={CloudLight}>
      <YourApp />
    </Theme>
  )
}

Multiple themes with runtime switching:

import { Theme } from '@ossy/design-system'
import { CloudLight, CloudDark } from '@ossy/themes'

<Theme
  theme={CloudLight}
  themes={{ light: CloudLight, dark: CloudDark }}
  defaultTheme="light"
>
  <YourApp />
</Theme>

Storybook

Component docs and MDX guides live in the ossy monorepo Storybook, not in a separate design-system dev server.

From the monorepo root (business/platform/ossy):

npm install   # if needed
npm start     # storybook dev -p 6006

Open in the browser:

• Design System → Getting Started — packages/design-system/docs/intro.mdx
• Design System → Principles, Theme Concepts, Patterns, Variants — other packages/design-system/docs/*.mdx
• Design System → Base / … — *.stories.jsx next to components

Static build: npm run build:storybook (runs generate:ts2doc first).

Storybook resolves @ossy/design-system from source (src/index.js), so you do not need lerna run build before npm start.

Layout guide

When to use what

| Need | Use | |------|-----| | Flex/grid, gaps, surfaces, app chrome grid | View with a layout preset and layout slot children | | Sectioned marketing page from a config array | Page + PageSection (each section is a View wrapper with max-width) | | Bordered vertical/horizontal list of panels | View with stack, horizontal, bordered, and View.Item | | Injectable header/sidebar/toolbar from packages | <Slot name="…" /> + *.component.jsx — see docs/SLOTS.md |

View layout presets

View is the primary layout primitive. Set layout to a preset (page, sidebar, off-center, column, row, …) and assign children with slot="header", slot="content", etc. Storybook Design System → Base → View shows each preset.

Page and PageSection

Page maps a sections array into PageSection blocks (title, max-width, render, optional slot). Use when you already model the screen as a list of sections (landing pages, wizards). For custom app shells, prefer a single View layout="page" and layout slots — closer to website-ossy layouts.

Stack → View (migration)

Stack and Stack.Item were removed. Use View with stack mode:

Before

import { Stack } from '@ossy/design-system'

<Stack horizontal bordered>
  <Stack.Item fill>…</Stack.Item>
  <Stack.Item>…</Stack.Item>
</Stack>

After

import { View } from '@ossy/design-system'

<View stack horizontal bordered>
  <View.Item fill>…</View.Item>
  <View.Item>…</View.Item>
</View>

• stack — enables stack item styling and borders
• horizontal — row direction (default column)
• bordered — separators between items
• View.Item — same as former Stack.Item (fill prop supported)

Icons (migration)

Legacy Material Icon and Icon2 are consolidated into a single Icon export.

| Before | After | |--------|--------| | Icon2 with name="arrow-right" | Icon with name="arrow-right" | | Legacy Icon with PascalCase / Material names | Icon with kebab-case css.gg name (see Storybook Design System → Base → Icon) | | icon= prop on some internals | Prefer name= (icon still accepted as alias) |

Icons load lazily per name. Unknown names log a warning and render empty.

import { Icon } from '@ossy/design-system'

<Icon name="check" size="m" variant="primary" />

Domain widgets (moved out)

These are no longer exported from @ossy/design-system:

| Former export | New home | |---------------|----------| | ProfileCard | @ossy/profile | | ResumeExperience, ResumeView | @ossy/resumes | | sections/* (Hero, marketing blocks, …) | Consumer feature packages or local app code — sections/ removed from design-system |

Install the feature package that owns the domain, or copy patterns using View + primitives.

Platform integration

• Pages — *.page.jsx primitives; use design-system for UI inside pages. PRIMITIVES.md
• Shell — app export const slots in *.layout.jsx maps shell:* to component ids; platform sets shell:content to the current page. docs/SLOTS.md, SHELL-SPEC.md
• Resource / input UI — *.component.jsx with metadata.id = resource:… or input:…

Deprecations and removed exports

Removed (breaking)

• Stack, Stack.Item — use View + stack / View.Item
• Legacy Material Icon — use Icon with kebab-case name
• Icon2 — renamed to Icon (same API)
• ProfileCard, ResumeExperience, ResumeView
• sections/* exports

Deprecated aliases (still exported; prefer canonical names)

| Deprecated | Use instead | |------------|-------------| | ComponentsProvider | ComponentSlotsProvider | | useComponentSlot | useSlot | | EditFields | Fields | | ResourceTemplateFields | Fields |

Further reading

• docs/SLOTS.md — layout vs component vs form field slots
• AUDIT.md — streamline audit and task status
• packages/platform/PRIMITIVES.md — platform file primitives

License

MIT