The Axiom01 Philosophy

Semantic Purity. Minimal Classes. Developer Delight.

Axiom01 is more than a UI framework—it's a philosophy that champions semantic HTML, minimal markup, and accessibility-first design. Our approach stands in stark contrast to the utility-heavy, class-bloated frameworks that dominate today's landscape.

1. Semantic First

Axiom01 is an HTML-centric framework. Your primary focus should always be on writing clean, semantic, and accessible HTML. The CSS is designed to style this semantic structure with minimal class-based intervention.

The Semantic Approach

If you find yourself adding classes to every element, you are not following the Axiom01 philosophy.

✅ Axiom01 Way

<article class="card">
  <header>
    <h3>Card Title</h3>
  </header>
  <p>Card content here</p>
  <footer>
    <button class="primary">Action</button>
  </footer>
</article>

❌ Other Frameworks

<div class="card p-4 bg-white shadow-lg">
  <div class="card-header border-b">
    <h3 class="text-lg font-bold">Title</h3>
  </div>
  <div class="card-body p-4">
    <p class="text-gray-600">Content</p>
  </div>
  <div class="card-footer">
    <button class="btn btn-primary">Action</button>
  </div>
</div>

2. No BEM, No Utility Stacking

This is a foundational principle of Axiom01. We explicitly forbid complex, multi-part class names and utility stacking.

Component-Level Classes

Assign a single, descriptive class to the root element of a component:

.card - not .card-container
.hero - not .hero-section
.navbar - not .nav-bar-wrapper

Descendant Styling

Style child elements using descendant selectors:

.card header - not .card-header
.card p - not .card-text
.navbar ul - not .navbar-list

Variant Classes

Use single, adjective-like classes for variations:

.primary - for primary buttons
.elevated - for elevated cards
.compact - for compact layouts

Absolutely No BEM

These patterns are strictly prohibited:

.card__header--large ❌
.button--primary--disabled ❌
.nav__item--active ❌

3. Accessible by Default

Accessibility is not an afterthought; it's a core requirement. By using semantic HTML and providing accessible components out of the box, we make it easier to build applications that can be used by everyone.

Semantic HTML Foundation

Proper HTML elements provide built-in accessibility:

Screen readers understand structure
Keyboard navigation works correctly
ARIA attributes are minimal but meaningful

WCAG 2.1 AA Compliance

Every component meets accessibility standards:

Color contrast ratios of 4.5:1 minimum
Focus indicators on interactive elements
Proper heading hierarchy

4. Themeable and Flexible

Axiom01 uses CSS custom properties (variables) to provide powerful theming capabilities while maintaining simplicity.

CSS Variables Power

Change one variable, update your entire application:

:root {
  --a-color-primary: #your-brand-color;
  --a-space-unit: 1.2rem;
  --a-border-radius-medium: 8px;
}

5. Developer Delight

Axiom01 is designed to make developers happy by reducing cognitive load and promoting maintainable code practices.

Less Mental Overhead

No need to memorize utility class names
Natural CSS cascade works as expected
Semantic HTML guides your decisions

Maintainable Code

Changes in CSS affect structure logically
Components remain readable months later
New team members understand code quickly

Philosophy in Action

Here's how Axiom01's philosophy translates into practical benefits:

Real-World Example: Contact Form

✅ Axiom01: 8 lines, semantic

<form class="contact">
  <div class="form-group">
    <label for="email">Email</label>
    <input type="email" id="email">
  </div>
  <button type="submit" class="primary">Send</button>
</form>

❌ Utility Framework: 14 lines

<form class="max-w-md mx-auto bg-white p-6">
  <div class="mb-4">
    <label class="block text-gray-700 text-sm font-bold mb-2" for="email">
      Email
    </label>
    <input class="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline" type="email" id="email">
  </div>
  <button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline" type="submit">
    Send
  </button>
</form>

Ready to Embrace the Philosophy?

Start building with Axiom01's semantic-first approach: