From fc639f0cdc2522e04f952dd96f0e0a0850976cd0 Mon Sep 17 00:00:00 2001
From: Eric Bailey <git@esb.lol>
Date: Thu, 4 Apr 2024 15:26:37 -0500
Subject: [PATCH] Button docs

---
 src/components/Button/README.md               | 61 +++++++++++++++++++
 .../{Button.tsx => Button/index.tsx}          |  0
 2 files changed, 61 insertions(+)
 create mode 100644 src/components/Button/README.md
 rename src/components/{Button.tsx => Button/index.tsx} (100%)

diff --git a/src/components/Button/README.md b/src/components/Button/README.md
new file mode 100644
index 0000000000..c28b4d4565
--- /dev/null
+++ b/src/components/Button/README.md
@@ -0,0 +1,61 @@
+# Button
+
+`Button` is intended to be very flexible and can be used to create consistent
+button styles, as seen in the Storybook, or can be used to create custom
+buttons with totally independent styles.
+
+## Usage
+
+Typical usage looks like this, where the `variant`, `size`, `color`, and/or
+`shape` are defined. Normal usage also should make use of the `ButtonText` and
+`ButtonIcon` components so that they inherit styles from the top level props
+like `color`.
+
+```tsx
+<Button
+  label='Typical button'
+  onPress={() => {}}
+  size='large'
+  variant='solid'
+  color='primary'
+>
+  <ButtonIcon icon={Plus} position='left' />
+  <ButtonText>Hello world</ButtonText>
+</Button>
+```
+
+Or:
+
+```tsx
+<Button
+  label='Typical button'
+  onPress={() => {}}
+  size='large'
+  variant='solid'
+  color='primary'
+>
+  <ButtonText>Hello world</ButtonText>
+  <ButtonIcon icon={Plus} position='right' />
+</Button>
+```
+
+Each of those top-level props props is optional in order to allow for "custom"
+buttons, like this:
+
+```tsx
+<Button label='Custom button' onPress={() => {}}>
+  {({ hovered, focused, pressed, disabled }) => (
+    <View style={[
+      t.atoms.bg_contrast_25,
+      hovered && t.atoms.bg_contrast_50,
+    ]}>
+      <Text>{disabled ? 'Disabled' : 'Click me!'}</Text>
+    </View>
+  ))}
+</Button>
+```
+
+In the custom button case, you have the _option_ to use `ButtonIcon` and
+`ButtonText`, but without top-level props like `color`, they serve little
+purpose, and it may be perferrable to define your own components for these
+purposes.
diff --git a/src/components/Button.tsx b/src/components/Button/index.tsx
similarity index 100%
rename from src/components/Button.tsx
rename to src/components/Button/index.tsx