elbwalker/apps/explorer

Explorer Component Library

Entry point for working with the walkerOS explorer component library.

Quick Reference

| Document | Purpose | | ---------------------- | ------------------------------------------------------------- | | AGENT.md | Architecture, code standards, SCSS compliance | | STYLE.md | Complete CSS variable reference (colors, spacing, typography) | | README.md | Usage guidelines, component patterns |

Core Principles

1. Controlled Components Only

All UI state via props. No useState for user-visible state.

// Correct: controlled
export function FormInput({ value, onChange, disabled }: Props) {
  return (
    <input
      value={value}
      onChange={(e) => onChange(e.target.value)}
      disabled={disabled}
    />
  );
}

// Wrong: internal state
export function FormInput() {
  const [value, setValue] = useState(''); // NO
}

2. Atomic Design Hierarchy

atoms/      → Single elements (Button, Input, Spinner)
molecules/  → Compositions (FormCard, Dropdown)
organisms/  → Complex layouts (Header, Sidebar)
demos/      → Full page examples

3. BEM Naming

.elb-{component}           // Block
.elb-{component}__{element} // Element
.elb-{component}--{modifier} // Modifier

// Example
.elb-alert
.elb-alert__title
.elb-alert--error

4. CSS Variables Only

Never use hardcoded values. Import from theme:

@use '../../theme/variables' as *;

.elb-button {
  background: var(--elb-color-primary);
  padding: var(--elb-spacing-sm) var(--elb-spacing-md);
  border-radius: var(--elb-radius-md);
  font-size: var(--elb-font-size-base);
}

File Structure

src/
├── components/
│   ├── atoms/
│   │   ├── button.tsx
│   │   ├── button.stories.tsx
│   │   └── ...
│   └── molecules/
│       ├── dropdown.tsx
│       └── ...
├── styles/
│   ├── theme/
│   │   └── _variables.scss    # All CSS variables
│   ├── components/
│   │   ├── atoms/
│   │   │   └── _button.scss
│   │   └── molecules/
│   │       └── _dropdown.scss
│   └── index.scss             # Import order matters
└── index.ts                   # Public exports

Creating Components

1. Component File

// src/components/atoms/spinner.tsx
import React from 'react';

export interface SpinnerProps {
  size?: 'sm' | 'md' | 'lg';
  className?: string;
}

export function Spinner({ size = 'md', className }: SpinnerProps) {
  return (
    <span
      className={`elb-spinner elb-spinner--${size} ${className || ''}`}
      role="status"
      aria-label="Loading"
    />
  );
}

2. Story File

// src/components/atoms/spinner.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Spinner } from './spinner';

const meta: Meta<typeof Spinner> = {
  title: 'Atoms/Spinner',
  component: Spinner,
  tags: ['autodocs'],
};
export default meta;

type Story = StoryObj<typeof Spinner>;

export const Default: Story = {};

export const Small: Story = {
  args: { size: 'sm' },
};

3. SCSS File

// src/styles/components/atoms/_spinner.scss
@use '../../theme/variables' as *;

.elb-spinner {
  display: inline-block;
  border: 2px solid var(--elb-color-border);
  border-top-color: var(--elb-color-primary);
  border-radius: 50%;
  animation: elb-spin 0.6s linear infinite;

  &--sm {
    width: 1rem;
    height: 1rem;
  }
  &--md {
    width: 1.5rem;
    height: 1.5rem;
  }
  &--lg {
    width: 2rem;
    height: 2rem;
  }
}

@keyframes elb-spin {
  to {
    transform: rotate(360deg);
  }
}

4. Register SCSS

Add import to src/styles/index.scss:

// Atoms
@use 'components/atoms/spinner';

5. Export Component

Add to src/index.ts:

export { Spinner } from './components/atoms/spinner';
export type { SpinnerProps } from './components/atoms/spinner';

Common CSS Variables

Colors

--elb-color-primary        // Brand blue
--elb-color-success        // Green for success states
--elb-color-warning        // Yellow/orange for warnings
--elb-color-error          // Red for errors
--elb-color-text           // Main text color
--elb-color-text-muted     // Secondary text
--elb-color-bg             // Background
--elb-color-bg-secondary   // Subtle backgrounds
--elb-color-border         // Default borders

Spacing

--elb-spacing-xs: 0.25rem // 4px
  --elb-spacing-sm: 0.5rem // 8px
  --elb-spacing-md: 1rem // 16px
  --elb-spacing-lg: 1.5rem // 24px
  --elb-spacing-xl: 2rem; // 32px

Typography

--elb-font-size-xs: 0.75rem // 12px
  --elb-font-size-sm: 0.875rem // 14px
  --elb-font-size-base: 1rem // 16px
  --elb-font-size-lg: 1.125rem // 18px
  --elb-font-size-xl: 1.25rem; // 20px

Borders & Shadows

--elb-radius-sm: 0.25rem --elb-radius-md: 0.5rem --elb-radius-lg: 0.75rem
  --elb-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05) --elb-shadow-md: 0 4px 6px
  rgba(0, 0, 0, 0.1);

Checklist

Before merging new components:

• [ ] Component is fully controlled (no internal state for user data)
• [ ] Props interface exported with component
• [ ] BEM class naming: .elb-{component}
• [ ] SCSS uses only CSS variables
• [ ] Story with tags: ['autodocs']
• [ ] SCSS imported in index.scss
• [ ] Component exported in index.ts
• [ ] Accessible (aria labels, roles, keyboard support)