@stordata/design-system 0.1.20260629080514

package/README.md

@@ -0,0 +1,66 @@
+# Design System
+
+Source of truth: https://zeroheight.com/239aea73f
+
+## Conventions
+
+### Implementation
+
+A component should either
+* Render a native HTML element, or
+* Render a component provided by BaseUI
+
+All components support the `render` prop from BaseUI. This prop is either forwarded to the root component, when rendering a
+BaseUI component, or used through the `useRender` hook when rendering a native HTML element, allowing further customization.
+
+All components support a set of common properties:
+* id
+* className
+* style
+* ref (a React ref)
+
+When implementing a new component, you should
+* Write a TypeScript interface for the component props, extending the common properties and `HTMLAttributes<T>` (or a sub-interface) to inherit default HTML props.
+* Use the `useMergeProps` to merge default properties coming from the theme with the properties passed to the component.
+* Add a section to the `Theme` interface for the default props of your new component, and choose default values.
+
+#### Props
+
+Except for component-specific props (like `variant`, `size`, etc.), all components should support spread props on the root element.  
+This is automatically handled by `useRender` when rendering a native HTML element, but needs to be manually done for BaseUI components.  
+This allows all native HTML props (like `style`, `onClick`, etc.) to be forwarded.
+
+#### Refs
+
+All components accept a `ref` that should always be used. Either
+* Forwarded to a BaseUI component (all of them accept refs), or
+* Given to `useRender` hook when rendering a native HTML element. See https://base-ui.com/react/utils/use-render#merging-refs
+
+### Styling
+
+Styling is done using a CSS module per component.  
+All CSS modules should always start with a root class, typically `.<component name>` that is applied to the root element of the component.
+
+When typing common styling properties, such as `color` or `size`, please always define a TypeScript type for the property,
+and use it in the component props interface. If the same set of values as the common ones is supported, you can use a type alias.
+
+For instance
+```typescript
+export type DSMyComponentSize = ComponentSize;
+```
+
+#### Sizing
+
+When applicable, components should support a `size` property that can be set to small, medium or large. The default size is medium.  
+In the component's CSS module, `.small`, `.medium` and `.large` classes should be defined to apply the appropriate styles for each size.  
+When rendering the component, use the `classNames` utility to apply the appropriate size class based on the `size` property.
+
+:bulb: It's OK to only support a subset of the available sizes.
+
+#### Variants
+
+When applicable, components should support a `variant` property that can be set to primary, secondary or tertiary. The default variant is primary.  
+In the component's CSS module, `.primary`, `.secondary` and `.tertiary` classes should be defined to apply the appropriate styles for each variant.  
+When rendering the component, use the `classNames` utility to apply the appropriate variant class based on the `variant` property.
+
+:bulb: It's OK to only support a subset of the available variants.