alf / README.md

# Bluesky's "Application Layout Framework" AKA "ALF"

Bluesky's design system and styling framework for React Native. ALF provides utility-first, atomic style objects that work across web, iOS, and Android.

You use ALF by combining static atoms (frozen style objects) with dynamic theme atoms that adapt to the active color scheme. No runtime CSS generation, no style strings. You compose styles via arrays, the same way you already do in React Native.

## Install

```bash
yarn add @bsky.app/alf
```

Peer dependencies: `react@19`, `react-native@^0.81.1`.

## Quick start

Wrap your app in the `Provider` and pass it your themes:

```tsx
import { Provider, themes } from '@bsky.app/alf'

function App() {
  return (
    <Provider activeTheme="light" themes={themes}>
      <Root />
    </Provider>
  )
}
```

Then use `atoms` for static layout and `useTheme()` for color:

```tsx
import { atoms as a, useTheme } from '@bsky.app/alf'

function Card() {
  const t = useTheme()
  return (
    <View style={[a.flex_row, a.gap_md, a.p_lg, a.rounded_md, t.atoms.bg]}>
      <Text style={[a.text_md, a.font_bold, t.atoms.text]}>Hello</Text>
    </View>
  )
}
```

## Platform behavior

ALF uses React Native's file extension convention (`.native.ts`) to resolve platform-specific code at build time.

Notable differences on native:

- `fixed` resolves to `position: 'absolute'` (fixed positioning not supported)
- `sticky` resolves to an empty object
- Border widths use `StyleSheet.hairlineWidth` instead of 1px
- Shadows use native shadow props with `elevation`. On Fabric (the new architecture), shadows resolve to empty objects.
- Web-only atoms (`inline`, `block`, `pointer`) resolve to empty objects

## API reference

See the [full API reference](./api-reference.md) for every export, token value, and platform-specific behavior.