Tujyane Application Layout Framework (ALF)

Modern, typed primitives for building consistent application layouts across web and React Native targets. Light theme only.

Overview

ALF provides:

• Atoms: 100+ minimal, composable atomic CSS classes exposed via atoms
• Palette: Direct color palette access with 90+ color tokens
• Semantic: Semantic color scales organized by purpose (primary, success, error, etc.)
• Tokens: Design tokens for consistent spacing, typography, and borders
• Utilities: Helper utilities like alpha, leading, flatten for style composition
• Platform helpers: platform.select wrapper and guards (web, ios, android, native) to keep code portable

Installation

pnpm add @tujyane/alf
# or
npm install @tujyane/alf
# or
yarn add @tujyane/alf

Peer dependencies expected:

• react
• react-native (for shared types like ViewStyle, even on web)

Quick Start

import { atoms, palette, tokens } from "@tujyane/alf";

export function App() {
  return (
    <div style={{ ...atoms.flex_col, ...atoms.gap_md }}>
      <header style={{ ...atoms.p_lg, backgroundColor: palette.primary_500 }}>
        <h1 style={{ ...atoms.text_2xl, color: palette.white }}>Hello World</h1>
      </header>
    </div>
  );
}

Exports

From src/index.tsx:

• atoms: Atomic CSS utility classes (flex, padding, margin, typography, etc.)
• palette: Color palette with 90+ color tokens
• semantic: Semantic color scales (primary, success, error, warning, info, secondary)
• platform: Platform helpers and selectors
• tokens: Design tokens namespace (spacing, typography, borders)
• utils: Utility helpers namespace (alpha, leading, flatten)
• TextStyleProp, ViewStyleProp: Convenience prop types for components

Design System

Color Palette

Access colors directly via the palette export:

import { palette } from "@tujyane/alf";

// Primary scale
const primary = palette.primary_500; // "#3563E9"

// Semantic colors
const success = palette.positive_500; // "#22C55E"
const error = palette.negative_500; // "#FF4423"
const warning = palette.warning_500; // "#FFC73A"
const info = palette.info_500; // "#54A6FF"

// Base colors
const white = palette.white; // "#FFFFFF"
const black = palette.black; // "#000000"

Semantic Color Scales

Use semantic scales for consistent color usage:

import { semantic } from "@tujyane/alf";

// Access any step in the scale
const primaryLight = semantic.primary[100]; // Lightest
const primaryBase = semantic.primary[500]; // Base
const primaryDark = semantic.primary[900]; // Darkest

// Available scales:
// - semantic.primary   (neutral/primary)
// - semantic.success   (green)
// - semantic.error     (red)
// - semantic.warning   (yellow)
// - semantic.info      (blue)
// - semantic.secondary (grayscale)

Atomic CSS

Compose styles using atomic classes:

import { atoms } from "@tujyane/alf";

// Layout
<div style={{ ...atoms.flex_row, ...atoms.gap_md, ...atoms.justify_between }}>

// Spacing
<div style={{ ...atoms.p_lg, ...atoms.mx_auto }}>

// Typography
<span style={{ ...atoms.text_lg, ...atoms.font_bold, ...atoms.text_center }}>

// Borders
<div style={{ ...atoms.rounded_md, ...atoms.border, borderColor: palette.primary_200 }}>

Available Atoms

Layout: flex, flex_col, flex_row, justify_center, justify_between, align_center, gap_sm, gap_md, gap_lg

Spacing: p_sm, p_md, p_lg, px_lg, py_md, m_auto, mx_auto, mt_lg, etc.

Typography: text_sm, text_md, text_lg, text_2xl, font_bold, text_center, leading_relaxed

Borders: rounded_sm, rounded_md, rounded_lg, rounded_full, border, border_t

Positioning: relative, absolute, fixed, inset_0, z_10, z_20

Design Tokens

Access raw design values:

import { tokens } from "@tujyane/alf";

// Spacing (in pixels)
const space = tokens.space.md; // 12

// Font sizes (in pixels)
const size = tokens.fontSize.lg; // 16.9

// Border radius
const radius = tokens.borderRadius.md; // 12

// Line heights (multipliers)
const height = tokens.lineHeight.snug; // 1.3

Platform Helpers

The framework exposes safe platform helpers in src/platform/index.ts:

• web(value), ios(value), android(value), native(value): Return value on the matching platform, undefined otherwise.
• platform(selectors): Equivalent to Platform.select returning the web option on web builds.

Usage:

import { web, android, platform } from "@tujyane/alf";

const maybeWebOnly = web({ behavior: "sticky" });

const style = platform({
  web: { cursor: "pointer" },
  android: { elevation: 2 },
  default: {},
});

Utilities

Available under the utils namespace:

• alpha(color, amount): Apply alpha to a color.
• leading(value): Compute leading (line-height) helpers.
• flatten(...): Flatten style arrays into a single object.

Import examples:

import { utils, palette } from "@tujyane/alf";

const translucent = utils.alpha(palette.black, 0.2);

Atoms and Types

• All atoms are re-exported from src/atoms via src/atoms/index.ts.
• Reusable types like ShadowStyle are defined in src/atoms/types.ts.

import { ShadowStyle } from "@tujyane/alf";

Contributing

1. Clone the repo
2. Install dependencies

pnpm i

3. Build

pnpm build

4. Run typecheck

pnpm typecheck

5. Develop against a local app or storybook of your choice.

FAQ

• Why React Native types on web?

  • We use react-native types like ViewStyle for cross-platform consistency. On web, they compile to plain objects.

• How do I customize colors?

  • Import the palette directly and override specific values, or use the semantic scales for consistent theming.

• Can I tree-shake utilities?

  • Yes, everything is module-scoped and re-exported. Use ESM imports for best results.

• Is dark mode supported?

  • No, this version only supports a light theme. For dark mode, you would need to manually swap color values or use a different approach.

License

MIT