Design Principles

Core principles that shape Elemnts UI's design and development.

Our Guiding Principles

Elemnts UI is designed with a focus on clarity, accessibility, flexibility, and developer joy. These principles ensure that every component is intuitive, powerful, and enjoyable to use.

We believe in naming things based on their purpose, not just their appearance. Instead of using visual terms like solid or outline, we use primary, secondary, and tertiary to create a logical hierarchy that aligns with how users interact with your interface. This approach is inspired by Uber's Base Design System.

import { Stack, Button } from "@elemnts-ui/react";

export function App() {
  return (
    <Stack direction="row" gap="8">
      <Button variant="primary">Primary Action</Button>
      <Button variant="secondary">Secondary Action</Button>
      <Button variant="tertiary">Tertiary Action</Button>
    </Stack>
  );
}

Built for Everyone

Accessibility isn't an afterthought—it's a foundation. Elemnts UI leverages Ark UI to ensure all components meet WCAG 2.1 AA standards. You get automatic ARIA attributes, seamless keyboard navigation, and managed focus states right out of the box.

import { SegmentGroup, Icon } from "@elemnts-ui/react";

<SegmentGroup defaultValue="list">
  <SegmentGroup.Indicator />
  <SegmentGroup.Item value="list">
    <SegmentGroup.ItemText>List View</SegmentGroup.ItemText>
    <SegmentGroup.ItemHiddenInput />
  </SegmentGroup.Item>
  <SegmentGroup.Item value="grid">
    <SegmentGroup.ItemText>Grid View</SegmentGroup.ItemText>
    <SegmentGroup.ItemHiddenInput />
  </SegmentGroup.Item>
</SegmentGroup>

Flexibility Without Complexity

Elemnts UI components are designed to adapt to your needs. Using the Compound Component pattern, you retain full control over rendering and element order. Whether you prefer dot notation or named exports, we support both to fit seamlessly into your workflow.

import { Accordion, Text } from "@elemnts-ui/react";

// Using Dot Notation
<Accordion defaultValue={["1"]}>
  <Accordion.Item value="1">
    <Accordion.ItemTrigger>Is it accessible?</Accordion.ItemTrigger>
    <Accordion.ItemContent>
      <Text>Yes! It follows WAI-ARIA patterns.</Text>
    </Accordion.ItemContent>
  </Accordion.Item>
</Accordion>

Predictable and Consistent

Consistency reduces cognitive load. Elemnts UI components share the same API patterns for sizing (xs to xl), variants, and customization. Whether you're styling a Button, Chip, or Avatar, the experience is familiar and intuitive.

/* Consistent sizing across components */
<Button size="lg" variant="primary">Click Me</Button>
<Chip size="lg" variant="secondary">Status</Chip>
<Avatar size="lg" src="..." />

TypeScript for Confidence

Elemnts UI is built in TypeScript, providing complete type safety. Enjoy robust IntelliSense, autocomplete for variants and tokens, and compile-time error detection to catch mistakes early.

import { ButtonProps } from "@elemnts-ui/react";

/* Type-safe variants and sizes */
<Button
  variant="primary" // Autocomplete: "primary" | "secondary" | "tertiary"
  size="md"        // Type checked: "xs" | "sm" | "md" | "lg" | "xl"
/>

/* Easy to extend */
interface CustomButtonProps extends ButtonProps {
  isLoading?: boolean;
}

A Joy to Use

Great documentation should empower, not confuse. Elemnts UI provides clear APIs, helpful error messages, and AI-friendly documentation. Explore our Storybook playground to see components in action and test them in real time.