@serenis/cdk

Core Development Kit for the Serenis design system. Provides layout primitives, structural components, responsive utilities, and markdown rendering — the building blocks that higher-level component libraries (ui, shared-components) are built on.

Install

npm install @serenis/cdk

Peer dependencies (must be installed by the consuming app):

• react >= 19.0.0
• styled-components >= 6.0.0
• @serenis/design-tokens

Quick start

# Build
yarn workspace cdk build

# Dev (watch mode)
yarn workspace cdk dev

# Test
yarn workspace cdk test

# Typecheck
yarn workspace cdk typecheck

# Lint
yarn workspace cdk lint
yarn workspace cdk lint:css

import { Flex, Pressable, PositionFixed, Form, MountOn, Space } from '@serenis/cdk'

Directory structure

libraries/cdk/
├── src/
│   ├── Flex/
│   │   ├── Flex.tsx                # Core styled layout primitive
│   │   ├── alias.tsx               # Position*, Overflow*, MaxWidth*, Form aliases
│   │   ├── backgroundProps.tsx     # Background color styling
│   │   ├── borderProps.tsx         # Border styling
│   │   ├── displayProps.tsx        # Display, overflow, opacity, hide
│   │   ├── elevationProps.tsx      # Elevation shadow styling
│   │   ├── flexboxProps.tsx        # Flexbox + responsive variants
│   │   ├── positionProps.tsx       # Position + insets
│   │   ├── sizeProps.tsx           # Min/max width/height
│   │   ├── spacingProps.tsx        # Padding + responsive variants
│   │   ├── index.ts                # Public exports
│   │   ├── index.test.tsx          # Tests
│   │   └── Playground.stories.tsx  # Storybook
│   ├── Pressable/                  # Unstyled button primitive
│   ├── Expandable/                 # Headless expand/collapse
│   ├── MountOn/                    # Conditional mount by media query
│   ├── OverflowAutoWithFadeEdges/ # Scroll area with gradient fades
│   ├── MarkdownRenderer/          # Markdown to React
│   ├── Space/                      # Inline whitespace separator
│   ├── PageLayout.tsx              # Page shell with max-width
│   ├── media/                      # Styled-components media helpers
│   ├── utils/
│   │   ├── props.ts                # PropsWithAs, ResponsiveProps, StyledProps
│   │   ├── renderMarkdown.ts       # Marked lexer + custom renderers
│   │   └── toValueOrPX.ts          # Number to px conversion
│   └── index.ts                    # Public API barrel
├── dist/                           # Built output (gitignored)
├── tsup.config.ts                  # Bundle config
└── package.json

Component catalog

Layout

| Export | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | | Flex | Foundational styled div with flexbox, spacing, sizing, border, background, elevation, and responsive props | | PositionFixed | Flex with position: fixed | | PositionAbsolute | Flex with position: absolute | | PositionRelative | Flex with position: relative | | PositionSticky | Flex with position: sticky | | OverflowAuto | Flex with overflow: auto and flexible sizing | | OverflowHidden | Flex with overflow: hidden | | MaxWidth320px–MaxWidth1260px | Flex with preset max-width constraints (320, 400, 448, 640, 840, 1024, 1260) | | Form | Flex rendered as <form noValidate> | | PageLayout | Page shell with horizontal padding and max-width inner container |

Interactive

| Export | Description | | ---------- | ------------------------------------------------------------------------------------- | | Pressable | Unstyled <button type="button"> with reset styling, loading state, and ARIA support | | Expandable | Headless expand/collapse with render props, Framer Motion animation, and ARIA |

Conditional & Overflow

| Export | Description | | ------------------------- | --------------------------------------------------------------------------------------- | | MountOn | Renders children only when a media query matches (viewport-based conditional rendering) | | OverflowAutoWithFadeEdges | Scrollable area with gradient fade edges on overflow sides |

Content

| Export | Description | | ---------------- | --------------------------------------------------------------------------------- | | Space | Inline <span role="separator"> with whitespace character | | MarkdownRenderer | Converts markdown text to React elements via marked with customizable renderers |

Utilities

| Export | Description | | --------------- | ----------------------------------------------------------------------------------------------- | | media | Styled-components tagged-template helpers for responsive CSS (media.gtMd, media.ltLg, etc.) | | PropsWithAs | Type helper for polymorphic as prop | | ResponsiveProps | Type helper for breakpoint-prefixed props | | StyledProps | Type helper for $-prefixed transient props | | toValueOrPX | Converts numbers to px strings, passes strings through (0 → '0' without px) | | renderMarkdown | Low-level markdown-to-React conversion with custom renderers |

Flex prop reference

All props use the $ prefix (transient — not forwarded to the DOM).

| Category | Props | | ---------- | --------------------------------------------------------------------------------- | | Flexbox | $direction, $align, $justify, $gap, $grow, $shrink, $wrap, $basis | | Spacing | $p, $pt, $pr, $pb, $pl, $px, $py | | Size | $minWidth, $maxWidth, $minHeight, $maxHeight | | Position | $position, $top, $right, $bottom, $left, $zIndex | | Display | $hide, $overflow, $opacity | | Border | $borderSize, $borderStyle, $borderColorName, $borderRadius | | Background | $backgroundColorName | | Elevation | $elevationName |

Responsive variants: flexbox, spacing, and $hide props have $md*, $lg*, $xl* breakpoint variants (e.g. $mdDirection, $lgGap, $xlHide).

Dependencies

| Dependency | Role | | ------------------- | ---------------------------------------------------------- | | design-tokens | Colors, spacing, typography, elevation, breakpoints (peer) | | react | React >= 19.0.0 (peer) | | framer-motion | Expand/collapse animation in Expandable | | functions | Pure utility functions | | hooks | Shared React hooks (useMediaQuery for MountOn) | | marked | Markdown parsing for MarkdownRenderer | | styled-components | CSS-in-JS (uses @sanity/styled-components fork, peer) |

Consumers

• Libraries: ui (most components), shared-components
• Apps: apps/web, apps/blog, apps/website, apps/nutrition-blog, apps/design-system

Documentation

• Storybook: Flex, Pressable, Expandable, MountOn, Space, and MarkdownRenderer have Playground stories in apps/design-system
• AGENTS.md: Agent-oriented API reference — see AGENTS.md

Build

Bundled with tsup into ESM + CJS + TypeScript declarations. Workspace dependencies are externalized.

License

PolyForm Noncommercial 1.0.0 — see LICENSE for the full text.