FrameOne

A modern, developer-first CSS utility framework inspired by Tailwind CSS — reimagined for clarity, structure, and scalability across modern React environments like CRA, Vite, and Next.js.

Features

• Semantic, human-readable class names (padding-x-1 vs. px-4)
• First-class React ecosystem integration
• Token-driven design system
• Semantic utility aliases (e.g. btn, card, badge)
• Type-safe developer experience

Installation

npm install frameone

Quick Start

1. Initialize a new FrameOne project:

npx frameone init

This will create a frameone.config.js file in your project root.

2. Build your CSS:

npx frameone build

3. Import the generated CSS in your project:

import './frameone.css';

Getting Started with Your Own Scenario

Creating your own UI with FrameOne is simple:

1. Create HTML/JSX files with FrameOne classes

// Example React component
function MyComponent() {
  return (
    <div className="container-md margin-x-auto padding-4">
      <h1 className="font-size-2xl font-weight-bold color-primary-700">
        My FrameOne App
      </h1>
      <div className="card padding-4 margin-top-4">
        <p className="font-size-md">
          This is a card component using FrameOne utility classes.
        </p>
        <button className="btn btn-primary margin-top-2">
          Click Me
        </button>
      </div>
    </div>
  );
}

2. Generate CSS for your scenario

npx frameone build

This will scan your files for FrameOne classes and generate only the CSS you need.

3. Use in your React app

// In your main component or entry file
import './frameone.css';

Common Utility Classes

Layout

• container-{size} - Responsive container (sm, md, lg, xl)
• padding-{size} - Padding on all sides (0-64)
• padding-x-{size} - Horizontal padding
• padding-y-{size} - Vertical padding
• margin-{size} - Margin on all sides
• margin-x-{size} - Horizontal margin
• margin-y-{size} - Vertical margin

Typography

• font-size-{size} - Font size (xs, sm, md, lg, xl, 2xl, etc.)
• font-weight-{weight} - Font weight (thin, light, normal, medium, bold, etc.)
• color-{color}-{shade} - Text color (primary-500, surface-800, etc.)
• text-align-{alignment} - Text alignment (left, center, right)

Components

• btn - Base button style
• btn-primary - Primary button variant
• card - Card component
• badge - Badge component
• grid-container - Grid layout

Responsive Design

Add responsive prefixes to any utility:

<div className="display-flex flex-direction-column sm:flex-direction-row">
  <!-- Stack vertically on mobile, horizontally on small screens and up -->
</div>

Available breakpoints: sm:, md:, lg:, xl:, 2xl:

State Variants

• hover: - Apply styles on hover
• focus: - Apply styles on focus
• active: - Apply styles on active state
• dark: - Apply styles in dark mode

<button className="btn hover:background-color-primary-700">
  Hover me
</button>

Creating a Custom Theme

Edit your frameone.config.js file to customize colors, spacing, typography, and more:

module.exports = {
  theme: {
    colors: {
      primary: {
        500: '#3b82f6',  // Change primary color
        // Add more shades...
      },
      // Add your brand colors...
      brand: {
        main: '#ff6b00',
        light: '#ff9d4d',
        dark: '#cc5500'
      }
    },
    // Customize other theme values...
  },
  variants: ['responsive', 'hover', 'focus', 'dark'],
  plugins: [],
};

Example Scenarios

Dashboard Layout

<div className="container-lg padding-4">
  <header className="display-flex justify-content-between align-items-center margin-bottom-6">
    <h1 className="font-size-3xl font-weight-bold">Dashboard</h1>
    <div>
      <button className="btn btn-primary">New Item</button>
    </div>
  </header>
  
  <div className="grid-container gap-4">
    <div className="card padding-4">
      <h2 className="font-size-xl margin-bottom-2">Statistics</h2>
      {/* Card content */}
    </div>
    <div className="card padding-4">
      <h2 className="font-size-xl margin-bottom-2">Recent Activity</h2>
      {/* Card content */}
    </div>
    <div className="card padding-4">
      <h2 className="font-size-xl margin-bottom-2">Performance</h2>
      {/* Card content */}
    </div>
  </div>
</div>

Product Card

<div className="card overflow-hidden">
  <div className="position-relative">
    <img src="product.jpg" className="width-100-percent" alt="Product" />
    <span className="badge position-absolute top-2 right-2 background-color-primary-500 color-surface-50">
      New
    </span>
  </div>
  <div className="padding-4">
    <h3 className="font-size-lg font-weight-semibold margin-bottom-2">Product Name</h3>
    <p className="color-surface-600 margin-bottom-4">Product description goes here...</p>
    <div className="display-flex justify-content-between align-items-center">
      <span className="font-size-xl font-weight-bold">$99.99</span>
      <button className="btn btn-primary">Add to Cart</button>
    </div>
  </div>
</div>

CLI Commands

• frameone init - Initialize a new FrameOne project
• frameone build - Build CSS based on classes in your project
• frameone watch - Watch files and rebuild in dev
• frameone tokens - Export design tokens (e.g. JSON, Figma-compatible)

Examples

Check out the examples directory for working samples:

• Create React App Example
• Vite Example
• Next.js Example

License

MIT