danielweinmann.com
forked from
esb.lol/alf
Bluesky's "Application Layout Framework"
More improvements to README and API reference
+33
-25
+1
-21
README.md
+1
-21
README.md
···
43
43
}
44
44
```
45
45
46
-
## Exports
47
-
48
-
Everything ships from one entry point: `@bsky.app/alf`.
49
-
50
-
| Export | Description |
51
-
|--------|-------------|
52
-
| `atoms` | 300+ frozen style objects for layout, spacing, typography, borders |
53
-
| `useTheme()` | Hook returning the active `Theme` with color-adaptive `atoms` |
54
-
| `Provider` | React context provider for theme selection |
55
-
| `tokens` | Namespaced design tokens (spacing, font sizes, line heights, radii, weights) |
56
-
| `utils` | Namespaced utilities: `alpha`, `leading`, `flatten`, `select` |
57
-
| `themes` | Pre-built light, dark, and dim theme objects |
58
-
| `createTheme()` | Build a custom theme from a palette |
59
-
| `createThemes()` | Build light/dark/dim variants from two palettes |
60
-
| `Palette` | Type and defaults for color palettes |
61
-
| `invertPalette()` | Flip a palette's color scale for dark mode |
62
-
| `isWeb`, `isNative`, `isIOS`, `isAndroid` | Platform detection booleans |
63
-
| `web()`, `native()`, `ios()`, `android()` | Platform-gated value selectors |
64
-
| `platform()` | `Platform.select()` equivalent |
65
-
66
46
## Platform behavior
67
47
68
48
ALF uses React Native's file extension convention (`.native.ts`) to resolve platform-specific code at build time.
···
77
57
78
58
## API reference
79
59
80
-
See [api-reference.md](./api-reference.md) for the complete API.
60
+
See the [full API reference](./api-reference.md) for every export, token value, and platform-specific behavior.
+32
-4
api-reference.md
+32
-4
api-reference.md
···
27
27
android,
28
28
platform,
29
29
} from '@bsky.app/alf'
30
+
31
+
import type {
32
+
Palette,
33
+
Theme,
34
+
ThemeScheme,
35
+
ThemeName,
36
+
ThemeAtoms,
37
+
TextStyleProp,
38
+
ViewStyleProp,
39
+
} from '@bsky.app/alf'
30
40
```
31
41
32
42
---
···
66
76
67
77
### `Context`
68
78
69
-
The raw React context (`React.Context<{ theme: Theme }>`). Defaults to `themes.light`. Display name: `'AlfContext'`.
79
+
The raw React context (`React.Context<{ theme: Theme }>`). Initial value uses `themes.light`. Display name: `'AlfContext'`.
70
80
71
81
You rarely need this directly. Use `useTheme()` instead.
72
82
···
578
588
579
589
### `invertPalette(palette)`
580
590
581
-
Flips **all four** color scales (contrast, primary, positive, negative) for dark mode. Swaps `_0`/`_25` with `_1000`/`_975`, and so on symmetrically. Keeps `white`, `black`, and `like` unchanged.
591
+
Flips **all four** color scales (contrast, primary, positive, negative) for dark mode. Swaps `_0`/`_25` with `_1000`/`_975`, and so on symmetrically. The `_500` center values in each scale remain unchanged. Keeps `white`, `black`, and `like` unchanged.
582
592
583
593
```typescript
584
594
const darkPalette = invertPalette(DEFAULT_PALETTE)
···
678
688
platform({ web: 16, default: 12 })
679
689
```
680
690
691
+
> On web, this uses `||` (not `??`), so falsy values like `0` or `""` for `specifics.web` will fall through to `specifics.default`.
692
+
681
693
---
682
694
683
695
## Utils
···
706
718
// Native: { lineHeight: 23 } (rounded pixel value)
707
719
```
708
720
709
-
Defaults to `tokens.fontSize.sm` and `tokens.lineHeight.snug` when values are missing.
721
+
Defaults to `tokens.lineHeight.snug` when `lineHeight` is missing. On native, also defaults to `tokens.fontSize.sm` when `fontSize` is missing (web does not use `fontSize`).
710
722
711
723
Returns: `Pick<TextStyle, 'lineHeight'>`
712
724
···
746
758
// { flexDirection: 'row', gap: 12 }
747
759
```
748
760
749
-
On both web and native, this delegates to `StyleSheet.flatten`. A custom fallback implementation exists for environments where neither `.web.ts` nor `.native.ts` is resolved.
761
+
On web and native, this delegates to `StyleSheet.flatten`. A custom fallback implementation is provided for other environments where neither `.web.ts` nor `.native.ts` is resolved.
750
762
751
763
Returns: merged style object
752
764
···
776
788
| Background | `bg`, `bg_contrast_25`, `bg_contrast_50`, `bg_contrast_100` through `bg_contrast_900`, `bg_contrast_950`, `bg_contrast_975` |
777
789
| Border | `border_contrast_low`, `border_contrast_medium`, `border_contrast_high` |
778
790
| Shadow | `shadow_sm`, `shadow_md`, `shadow_lg` |
791
+
792
+
### `Palette`
793
+
794
+
Color value map for a theme. See [Palette](#palette) for the full shape.
795
+
796
+
### `Theme`
797
+
798
+
Complete theme object containing scheme, name, palette, and atoms. See [Themes](#themes) for details.
799
+
800
+
### `ThemeScheme`
801
+
802
+
`'light' | 'dark'`
803
+
804
+
### `ThemeName`
805
+
806
+
`'light' | 'dark' | 'dim'`
779
807
780
808
---
781
809