Launch workspace

Components share theme tokens, typed variants, spacing, and semantic metadata.

) } export function App() { return ( ) } ``` `defaultMode` sets the initial uncontrolled mode. `toggleMode()` updates the provider, so Marwes components, preset CSS, and custom app styles that use `--mw-*` variables all move together without duplicating local theme state. ### System And Persisted Preference `mode` is always the rendered visual mode: `ThemeMode.light` or `ThemeMode.dark`. `preference` is the app or user choice: `ThemeMode.light`, `ThemeMode.dark`, or `"system"`. Use `preference` and `defaultPreference` when your UI needs a system option; keep using `mode`, `defaultMode`, and `onModeChange` when you only need concrete light/dark compatibility. ```tsx import { Button, ButtonVariant, MarwesProvider, ThemeMode, useThemeMode } from "@marwes-ui/react" function ThemeMenu() { const { mode, preference, systemMode, isSystem, setPreference, setMode } = useThemeMode() return (

Rendering {mode}; preference is {preference}; system is {systemMode}.

{isSystem ? "Following system" : null}

) } export function App() { return ( ) } ``` `useThemeMode().mode` never returns `"system"`; it is always the concrete mode Marwes rendered. `useThemeMode().preference` returns the active app/user preference, and `setPreference("system")` is the system-capable setter. `setMode(mode)` remains a concrete light/dark convenience. `storageKey` is opt-in and defaults to `false`. Storage reads and writes are failure-safe, so private browsing or unavailable storage will fall back to normal provider state. `enableSystem` defaults to `true`; set it to `false` to avoid `matchMedia` detection and resolve `"system"` through the light fallback. This layer does not provide SSR no-flash behavior. Server output can still render the fallback mode before the client applies a stored or system preference. Use it for client-side preference and persistence, not for a no-flash SSR guarantee. ### Root Target Sync By default Marwes keeps theme state scoped to the provider element. If your app shell also needs the resolved mode on `html` or `body`, set `target` and `attribute`: ```tsx ``` `target` can be `"provider"`, `"html"`, or `"body"`. `attribute` can be `"class"`, `"data-theme"`, or `"data-mode"`. Class mode only adds the active `light` / `dark` class and removes the opposite one; unrelated classes are preserved. The provider root still keeps `mw-theme--light` / `mw-theme--dark` and provider-scoped `--mw-*` variables in every target mode. Use one global-target provider per app shell. If multiple providers target `html` or `body`, deciding which provider owns that global element is app-owned behavior. ### Tailwind And shadcn Compatibility Marwes is compatible with Tailwind and shadcn-style dark variants through `target="html" attribute="class"`. App-owned Tailwind tokens can also reference Marwes `--mw-*` variables when rendered inside the provider subtree. ```tsx ``` Read the [Tailwind and shadcn integration guide](https://github.com/niklas-westman/marwes/blob/main/docs/guides/tailwind-shadcn-integration.md) for Tailwind v3/v4 examples, token mapping, provider-scoped variable limits, and the SSR no-flash boundary. ### Next.js App Router SSR Use `MarwesThemeStyle`, `MarwesThemeScript`, and `variableStrategy="style-tag"` when a server-rendered app needs the correct light or dark variables before hydration. This is opt-in; normal React apps keep inline provider variables by default. Read the [theme SSR no-flash guide](https://github.com/niklas-westman/marwes/blob/main/docs/guides/theme-ssr-no-flash.md) for Next.js App Router setup, CSP nonces, `suppressHydrationWarning`, custom light/dark themes, and stored/system preference behavior. For a simple brand pass, override shared values once and let Marwes fill the rest. If your product needs different brand colors in light and dark mode, control `mode` and switch between two small `ThemeInput` override objects: ```tsx import { useState } from "react" import { Button, ButtonVariant, MarwesProvider, ThemeMode, type ThemeInput, useThemeMode, } from "@marwes-ui/react" const themeByMode = { [ThemeMode.light]: https://github.com/niklas-westman/marwes/blob/main/packages/react/{ color: { primary: "#2457FF", background: "#F8FAFC", surface: "#FFFFFF", text: "#111827", border: "#D1D5DB", focus: "#2457FF", }, }, [ThemeMode.dark]: https://github.com/niklas-westman/marwes/blob/main/packages/react/{ color: { primary: "#8BA2FF", background: "#0B1020", surface: "#111827", text: "#F8FAFC", border: "#334155", focus: "#93C5FD", }, }, } satisfies Record function ThemeToggle() { const { mode, toggleMode } = useThemeMode() return ( ) } export function App() { const [mode, setMode] = useState(ThemeMode.light) return ( ) } ``` Mode-specific defaults fill every omitted token, so each override can stay small. `theme={{ mode: ThemeMode.dark }}` is still enough for the default dark baseline. ## Custom Styling Tokens `MarwesProvider` resolves `ThemeInput` into `--mw-*` CSS variables. Marwes components and preset CSS consume those variables automatically. The custom styling token helpers let app-owned styles use the same provider-scoped values instead of hard-coding colors, spacing, radius, typography, or duplicated `var(...)` strings. Use the helpers by purpose: - `mwThemeVars` is the default styling helper. It returns CSS `var(...)` references for styled-components, Emotion, vanilla-extract, inline style values, and config files. - `mwThemeVarNames` returns raw custom property names for assigning provider-scoped overrides in style objects or tooling. - `mwVar()` wraps custom or advanced `--mw-*` names when the named token object does not cover a specialized case. - `mwTheme` is a plain object that mirrors `mwThemeVars` for styled-components or Emotion `ThemeProvider` usage. `mwStyledTheme` remains as a deprecated compatibility alias. ```tsx import type { ReactNode } from "react" import { mwTheme, mwThemeVarNames, mwThemeVars, mwVar } from "@marwes-ui/react" import styled, { ThemeProvider } from "styled-components" const Panel = styled.section` padding: ${mwThemeVars.spacing.sp24}; color: ${mwThemeVars.color.text}; background: ${mwThemeVars.color.surface}; border-radius: ${mwThemeVars.ui.radius}; ` const InlinePanel = () => (

) const AppTheme = ({ children }: { children: ReactNode }) => ( {children} ) ``` `mwTheme`, `mwStyledTheme`, and `mwThemeVars` contain CSS `var(--mw-*)` references, not resolved color or spacing values. They are correct inside styled CSS evaluated below `MarwesProvider`, but JavaScript reads or aliases taken from `props.theme` can resolve against the wrong element and return an empty value. Use `useTheme()` for JavaScript logic, charts, runtime aliases, or bridges that need concrete values. Plain CSS and CSS Modules do not need a JavaScript bridge: ```css .panel { padding: var(--mw-spacing-sp-24); color: var(--mw-color-text); border-radius: var(--mw-ui-radius); } ``` This enables React apps to keep custom panels, local layouts, third-party CSS-in-JS components, and design-tool integrations visually tied to the same active theme as Marwes components. Changing `MarwesProvider theme={...}` updates both preset components and app-owned styles. Keep the APIs separate: - Use `Spacings.sp24` for Marwes spacing props such as ``. - Use `mwThemeVars.spacing.sp24` for custom CSS values. - Use `mwThemeVarNames.spacing.sp24` when assigning or inspecting a CSS custom property name. - Use `useTheme()` when React logic needs resolved runtime values such as `"#2457FF"`. ## Google Fonts DX Most Google Font use cases only need `mwAvailableFonts`; no `fontLoading` prop is needed. ```tsx import { MarwesProvider, mwAvailableFonts, type ThemeInput } from "@marwes-ui/react" const fontTheme = { font: { primary: mwAvailableFonts.Poppins, secondary: mwAvailableFonts.Lora, }, } satisfies ThemeInput ``` For self-hosted or licensed fonts, use `BrandSans`, `BrandSerif`, `BrandMono`, or `createFontStack()`. ## Semantic Buttons Prefer purpose components for common actions. They lock UX intent and emit AI-readable metadata, so the component is not just "a button with red styling" but a known action with known risk. ```tsx import { CancelButton, CreateButton, DestructiveButton, SubmitButton, } from "@marwes-ui/react" Cancel Create Save Delete ``` That matters for agentic workflows. A human, test, or AI agent can inspect the DOM and see that a destructive button requires confirmation before activation: ```html ``` An agent can then follow a safer rule: if `data-confirmation-required="true"`, ask the user before clicking. A test can assert the same behavior without guessing from the label "Delete" or from a red color. Use raw `Button` props when you intentionally need a custom combination. ```tsx import { Button, ButtonAction, ButtonSize, ButtonVariant } from "@marwes-ui/react" ``` ## Why It Is Accessible Marwes React components are accessible because the adapter renders a shared core contract, not because each component hand-rolls ARIA in isolation. - Core recipes produce typed `a11y` output for roles, labels, described-by wiring, invalid state, disabled state, and semantic metadata. - React components prefer native DOM controls first: `button`, `input`, `select`, `textarea`, `hr`, and standard form wiring. - Field components connect visible labels, helper text, and errors through `id`, `htmlFor`, `aria-describedby`, `aria-invalid`, and polite error announcements. - Coordinated widgets carry explicit contracts: tabs wire `tablist`/`tab`/`tabpanel`, dialogs own dialog semantics, toasts expose live-region behavior, and purpose buttons expose risk metadata. - Storybook accessibility smoke checks run through the Storybook a11y addon for the promoted React families, and shared contract tests keep React aligned with Vue. Example: ```tsx import { InputField, type InputFieldProps } from "@marwes-ui/react" const receiptEmailField = { label: "Email", helperText: "Used for receipts.", error: "Enter a valid email.", input: { type: "email", placeholder: "you@example.com" }, } satisfies InputFieldProps ``` That contract resolves to DOM wiring like: ```html Email

Used for receipts.

Enter a valid email.

``` The important part is that the same label, helper, error, and invalid contract is tested at the shared contract layer and then applied by the React adapter. ## Package Boundaries - `@marwes-ui/core` owns recipes, theme resolution, a11y mapping, and semantic metadata. - `@marwes-ui/presets` owns default preset CSS. - `@marwes-ui/react` owns React rendering and provider behavior. ## Scripts ```bash pnpm --filter @marwes-ui/react build pnpm --filter @marwes-ui/react typecheck pnpm --filter @marwes-ui/react test ``` ## Related Docs - [Docs index](https://github.com/niklas-westman/marwes/tree/main/docs) - [Architecture](https://github.com/niklas-westman/marwes/blob/main/docs/reference/architecture.md) - [Figma to Marwes](https://github.com/niklas-westman/marwes/blob/main/docs/guides/figma-to-marwes.md)