Tujyane Application Layout Framework (ALF)

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

Overview

ALF provides:

• Theme provider: Context-driven theming with Provider, useTheme, and predefined themes and palette.
• Atoms: Minimal, composable building blocks exposed via src/atoms.
• Tokens: Design tokens exported as tokens for consistent spacing, typography, and colors.
• Utilities: Helper utilities like alpha, leading, flatten, and select for style composition.
• Platform helpers: platform.select wrapper and guards (web, ios, android, native) to keep code portable.

The package re-exports from src/index.tsx so consumers can import from a single entrypoint.

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 { Provider, themes } from "@tujyane/alf";

export function App() {
  return (
    <Provider
      activeTheme="light"
      themes={{ light: themes.light, dark: themes.dark }}
    >
      {/* app routes/components */}
    </Provider>
  );
}

Access the theme anywhere:

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

export const Header = () => {
  const theme = useTheme();
  return (
    <header style={{ backgroundColor: theme.background, color: theme.text }}>
      My App
    </header>
  );
};

Exports

From src/index.tsx:

• Provider: React provider to set the active theme.
• useTheme: Hook to read the current theme (returns Theme with scheme, palette, semantic, atoms).
• Context: Internal context (typed) for advanced usage.
• themes: Theme presets (light, dark).
• palette: Color palette helpers.
• platform: Platform helpers and selectors.
• tokens: Design tokens namespace (spacing, typography, borders).
• utils: Utility helpers namespace (alpha, leading, flatten, select).
• TextStyleProp, ViewStyleProp: Convenience prop types for components.
• atoms: All atoms from src/atoms are re-exported.

Theming

import { Provider, themes } from "@tujyane/alf";

type ThemeKey = "light" | "dark";

const appThemes = { light: themes.light, dark: themes.dark } as const;

export const Root = ({ children }: React.PropsWithChildren) => (
  <Provider<ThemeKey, typeof appThemes> activeTheme="light" themes={appThemes}>
    {children}
  </Provider>
);

useTheme() returns the active Theme object so you can style components consistently.

Design System

Color Scales

The framework provides semantic color scales mapped from the palette:

• Primary (neutral): primary_25 through primary_900 - used for text, backgrounds, and borders
• Success: positive_100 through positive_900 - green/success states
• Error: negative_100 through negative_900 - red/error states
• Warning: warning_100 through warning_900 - yellow/warning states
• Info: info_100 through info_900 - blue/information states
• Secondary: secondary_100 through secondary_900 - accent colors

Theme Atoms

Access pre-composed atoms via theme.atoms:

Base (using primary neutral scale):

• Text: text, text_low, text_medium, text_high, text_inverted
• Backgrounds: bg, bg_25, bg_50
• Borders: border_low, border_medium, border_high

Semantic (using color scales):

• Text: text_primary, text_success, text_error, text_warning, text_info, text_secondary
• Backgrounds: bg_primary, bg_success, bg_error, bg_warning, bg_info, bg_secondary
• Borders: border_primary, border_success, border_error, border_warning, border_info, border_secondary

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

const Button = () => {
  const theme = useTheme();
  return (
    <button style={{ ...theme.atoms.bg_primary, ...theme.atoms.text_inverted }}>
      Click me
    </button>
  );
};

Accessing Semantic Colors

const theme = useTheme();

// Access semantic color scales directly
const primaryColor = theme.semantic.primary[500];
const errorText = theme.semantic.error[900];

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.
• select(map, key): Safe selection helper.

Import examples:

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

const translucent = utils.alpha("#000", 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. 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 add new themes?

  • Export them from src/themes.ts and pass via Provider as the themes prop.

• Can I tree-shake utilities?

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

License

MIT