Design philosophy

These are the rules the library follows. Each one answers a problem described in Why a separate library.

Figma is the visual source of truth

A component is designed in Figma first. The designer’s file, “Tourism Suite - New”, holds the screens; the “Sulmu UI” library file mirrors every component in the package. If code and Figma disagree about how something looks, Figma is right and the code is fixed, or the design is changed in Figma first.

Tokens first

Colours, type, spacing, radii and shadows live in tokens/*.json. Those files generate the Panda preset the components are built with, and the Figma variables are created from the same files. Nothing else defines a value.

• A Figma variable name is the token path: color/bg/surface is colors.bg.surface, and in CSS it is --su-colors-bg-surface.
• Components only use semantic tokens (bg.surface, fg.muted), never a primitive colour or a raw pixel value. That is what makes dark mode a switch rather than a rewrite.

See The tokens workflow.

Ark UI for behaviour, Panda CSS for style

The two jobs are kept apart.

• Ark UI provides behaviour and accessibility: focus management, keyboard interaction, ARIA attributes, positioning of popups. It has no styles.
• Panda CSS provides style. Each component has a recipe: a typed description of its base style and its variants, written with token names.

A library component is a thin layer that joins the two and gives them a small, fixed API.

Precompiled CSS

Panda turns every recipe into plain CSS at build time. The package ships one stylesheet, @beyul/sulmu-ui/styles.css, with every variant of every component in it. An app needs no Panda, no Emotion and no provider: it imports the CSS once and uses the components.

The su prefix and no reset

Every class (.su-button) and every CSS variable (--su-colors-brand-600) has the prefix su, and the stylesheet does not reset or restyle anything outside the library’s own elements. The library can be added to an existing app, next to Chakra or any other CSS, without either side changing how the other looks. That is what makes a screen-by-screen migration possible.

Names shared between Figma and code

A component prop has the same name and values as the variant property in Figma: variant=primary, size=sm in the Figma inspector is <Button variant="primary" size="sm"> in code. Icons follow the same rule: icon/edit-2 in Figma is edit-2.svg in the package and Edit2Icon in code. Nobody has to translate.

Hand-written prop types

The props of each component are written out by hand in its file, with a comment on each one. They are not derived from Panda’s generated types. Two reasons:

• The published .d.ts files stand alone. An app gets full types without having Panda installed or generating anything.
• The API is deliberate. A prop exists because someone decided it should, not because a recipe happens to have a variant.

The props tables on this site are generated from those same interfaces.

A small, fixed API

Components take a few named props rather than open style props. There is no p={4} or color="red.500" on a Button. Layout is done with Flex, Stack and Grid, text with Text, and one-off adjustments with className or style. When the same adjustment keeps coming back, that is a signal to add a variant to the library. See Styling and extending.