From 6b64eeea5c5a523290479265ce308ca1b2e68601 Mon Sep 17 00:00:00 2001
From: Eric Bailey <git@esb.lol>
Date: Mon, 8 Jan 2024 19:40:17 -0600
Subject: [PATCH] Some docs, fix line-height values, export tokens

---
 src/alf/README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++
 src/alf/atoms.ts  | 23 ++++----------------
 src/alf/index.tsx |  1 +
 3 files changed, 60 insertions(+), 19 deletions(-)

diff --git a/src/alf/README.md b/src/alf/README.md
index 5f602c8d33..aa31bcf988 100644
--- a/src/alf/README.md
+++ b/src/alf/README.md
@@ -1 +1,56 @@
 # Application Layout Framework (ALF)
+
+A set of UI primitives and components.
+
+## Usage
+
+Naming conventions follow Tailwind — delimited with a `_` instead of `-` to
+enable object access — with a couple exceptions:
+
+**Spacing**
+
+Uses "t-shirt" sizes `xxs`, `xs`, `sm`, `md`, `lg`, `xl` and `xxl` instead of
+increments of 4px. We only use a few common spacings, and otherwise typically
+rely on many one-off values.
+
+**Text Size**
+
+Uses "t-shirt" sizes `xxs`, `xs`, `sm`, `md`, `lg`, `xl` and `xxl` to match our
+type scale.
+
+**Line Height**
+
+The text size atoms also apply a line-height with the same value as the size,
+for a 1:1 ratio. `tight` and `normal` are retained for use in the few places
+where we need leading.
+
+### Atoms
+
+An (mostly-complete) set of style definitions that match Tailwind CSS selectors.
+These are static and reused throughout the app.
+
+```tsx
+import { atoms } from '#/alf'
+
+<View style={[atoms.flex_row]} />
+```
+
+### Theme
+
+Any values that rely on the theme, namely colors.
+
+```tsx
+const t = useTheme()
+
+<View style={[atoms.flex_row, t.atoms.bg]} />
+```
+
+### Breakpoints
+
+```tsx
+const b = useBreakpoints()
+
+if (b.gtMobile) {
+  // render tablet or desktop UI
+}
+```
diff --git a/src/alf/atoms.ts b/src/alf/atoms.ts
index 5c41f8c98a..c142f5f716 100644
--- a/src/alf/atoms.ts
+++ b/src/alf/atoms.ts
@@ -153,26 +153,11 @@ export const atoms = {
     fontSize: tokens.fontSize.xxl,
     lineHeight: tokens.fontSize.xxl,
   },
-  leading_xxs: {
-    lineHeight: tokens.fontSize.xxs,
+  leading_tight: {
+    lineHeight: 1.25,
   },
-  leading_xs: {
-    lineHeight: tokens.fontSize.xs,
-  },
-  leading_sm: {
-    lineHeight: tokens.fontSize.sm,
-  },
-  leading_md: {
-    lineHeight: tokens.fontSize.md,
-  },
-  leading_lg: {
-    lineHeight: tokens.fontSize.lg,
-  },
-  leading_xl: {
-    lineHeight: tokens.fontSize.xl,
-  },
-  leading_xxl: {
-    lineHeight: tokens.fontSize.xxl,
+  leading_normal: {
+    lineHeight: 1.5,
   },
   font_normal: {
     fontWeight: tokens.fontWeight.normal,
diff --git a/src/alf/index.tsx b/src/alf/index.tsx
index ce8f5e967f..1daa0bfedc 100644
--- a/src/alf/index.tsx
+++ b/src/alf/index.tsx
@@ -2,6 +2,7 @@ import React from 'react'
 import {Dimensions} from 'react-native'
 import * as themes from '#/alf/themes'
 
+export * as tokens from '#/alf/tokens'
 export {atoms} from '#/alf/atoms'
 export * from '#/alf/util/platform'