repository·master·Indexed 41 days ago
https://github.com/reaviz/reablocksA React-based UI component library featuring over 50 components styled with Tailwind CSS. Designed with a dark-first approach, Reablocks provides a comprehensive design system including semantic color tokens, a typography scale using Inter and Fira Code, and specific layout guidelines for rapid interface development. Version 10.3.1.
reablocks uses a semantic token API for styling. Instead of using raw color values, you should use semantic tokens which adapt automatically between dark and light modes.
primary: The brand accent (electric blue #105eff). Used for primary actions, selected states, and links. Hover state brightens to primary-hover in dark mode.secondary: Charcoal (#242433) for secondary button fills. In light mode, this resolves to a pale blue (#c3d7ff).panel: The base background (#02020f in dark).panel-accent: The hairline border color used for cards, inputs, and dialogs.surface: Raised interactive surfaces like toggle tracks and dividers.text-primary: Main text color (#f7f7fa in dark).text-secondary: Muted text/labels (#77778c in dark).on-primary: The color for labels/icons sitting on top of primary/success/error/warning surfaces. Note: This is always near-white in both dark and light modes.success, error, warning, info: Used for state-specific feedback. Each has a -hover variant and a dark -background tint for callouts in dark mode.| Token | Dark (Default) | Light |
|---|---|---|
primary | #105eff | #105eff |
secondary | #242433 | #c3d7ff |
panel | #02020f | #ffffff |
panel-accent | #242433 | #e6e6f0 |
surface | #242433 | #c9c9d6 |
text-primary | #f7f7fa | #11111f |
text-secondary | #77778c | #242433 |
reablocks is a Tailwind CSS-powered React component library designed with a dark-first approach.
Key design characteristics:
<token>-light variants (e.g., primary-light). The underlying palette primitives remain unchanged.Reablocks components follow a strict design system based on semantic tokens and shared scales.
primary, success). Labels use {colors.on-primary} (white in both modes) except for button-secondary which uses {colors.text-primary}.small (12px label), medium (14px label, default), large (20px label).{colors.gray-600} with {colors.gray-400} text.{colors.panel} with a 1px {colors.panel-accent} border and {rounded.xs} corners.{colors.error}.#77778c in both modes; background is a muted tint; underline is removed.{colors.gray-400} stroke; checked is {colors.blue-500} with a white check.{colors.surface} border. Selected state uses {colors.primary-active} border and a {colors.primary} dot.{colors.surface}. Turns {colors.primary} when 'on'.{rounded.xs} corners. Default is {colors.panel} with primary text. Color variants fill with semantic tokens and flip text to {colors.panel} for contrast.{colors.panel} with a 1px {colors.panel-accent} border and {rounded.xs} corners.{colors.panel-accent} background, {rounded.sm} corners, and 0.375rem padding.{colors.panel} sheet with {colors.panel-accent} border, {rounded.sm} corners, and shadow-2xl.To maintain visual consistency and ensure theme compatibility, follow these rules:
primary, panel, surface, and text-primary for surfaces and text. These resolve correctly in both light and dark modes.xs–4xl), typography (10–16px), and spacing (0.25rem grid).theme-light/theme-dark classes or data-theme attributes on the root element.teal-500, violet-400) for non-semantic accents like charts or category colors.extendTheme, extendComponentTheme, or the theme prop) instead of external CSS or !important to ensure deep-merging works correctly.gray-700 or gray-950 for surfaces/text; use surface or panel instead.To run the Reablocks development environment locally and explore components in Storybook, follow these steps:
npm i.npm start.This will automatically open your browser to the Storybook page where you can interact with the components.
npm i
npm startTo maintain the 'engineered' reablocks aesthetic, follow these layout and shape constraints:
spacing.unit (0.25rem).0.5rem x 1rem0.375rem x 0.625rem1.75rem all aroundAvoid medium-rounded corners (8–12px) as they break the visual identity. Use the following:
rounded.xs (2px): For structural elements like buttons, cards, inputs, and chips.rounded.sm (4px): For tooltips and dialogs.rounded.full: For small controls like toggles, radios, and badges.Avoid heavy shadows. Hierarchy is achieved through layered darkness and hairline borders:
colors.panel (#02020f)colors.surface (#242433)colors.panel-accent border.shadow-2xl).Reablocks uses Playwright to perform visual regression testing by taking screenshots of every Storybook story to detect unintended visual changes.
Prerequisites: Storybook must be running on localhost:9009. If it is not running, Playwright will attempt to start it automatically.
Use the following commands to manage visual tests:
npm run test:visualnpm run test:visual:updateNote: test:visual:extract runs automatically during these commands to fetch the story list from Storybook.
# Run visual tests against existing baseline screenshots
npm run test:visual
# Update baseline screenshots (after intentional visual changes)
npm run test:visual:updateBy default, reablocks uses a dark-first theme. To switch to the complete light theme, add the theme-light class or the data-theme="light" attribute to a root element in your application.
All component styling is driven by a centralized theme system. To ensure correct rendering in both modes, always reference semantic tokens (e.g., primary, panel) rather than hardcoding hex values. The theme system automatically resolves semantic tokens to their -light counterparts when the light theme is active.
<!-- Using class -->
<div class="theme-light">
<!-- components here -->
</div>
<!-- Using data attribute -->
<div data-theme="light">
<!-- components here -->
</div>If you encounter issues or need assistance with reablocks, you can use the following channels:
The src/utils/Theme/index.ts file serves as the central export point for the Reablocks theming system. It aggregates all necessary components, types, and utilities required to manage and apply themes across your application.
To implement theming, you will primarily interact with the following modules:
ThemeProvider: The component used to inject theme context into your component tree.themes: Pre-defined theme objects or definitions.hooks: React hooks for consuming theme data (e.g., accessing current colors or spacing) within functional components.types: TypeScript definitions for theme structures and configuration.blocks: Theme-aware block configurations.helpers: Utility functions for theme manipulation and calculation.