docs: explain theme customization more (#9)

Author: ChristopherChudzicki

src/components/Button/ActionButton.stories.tsx

@@ -41,6 +41,9 @@ const EDGES = enumValues<NonNullable<ActionButtonProps["edge"]>>({
   none: true,
 })
 
+/**
+ * A button that should contain a remixicon icon and nothing else.
+ */
 const meta: Meta<typeof ActionButton> = {
   title: "smoot-design/ActionButton",
   component: ActionButton,
@@ -166,6 +169,13 @@ export const Showcase: Story = {
   ),
 }
 
+/**
+ * `ActionButtonLink` is styled as a `ActionButton` that renders an anchor tag.
+ *
+ * To use a custom link component (E.g. `Link` from `react-router` or `next/link`),
+ * pass it as the `Component` prop. Alternatively, customize the project-wide
+ * default link adapter via [Theme's LinkAdapter](../?path=/docs/smoot-design-themeprovider--docs)
+ */
 export const Links: Story = {
   render: () => (
     <Stack direction="row" gap={2} sx={{ my: 2 }}>

src/components/Button/Button.tsx

@@ -315,11 +315,11 @@ const ButtonInner: React.FC<
 type ButtonProps = ButtonStyleProps & React.ComponentProps<"button">
 
 /**
- * Our standard button component.
+ * Our standard button component. See [Button Docs](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-button--docs).
  *
  * See also:
- * - ButtonLink
- * - ActionButton
+ * - [ButtonLink](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-button--docs#links)
+ * - [ActionButton](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-actionbutton--docs) for icon-only uses
  */
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   ({ children, ...props }, ref) => {
@@ -336,6 +336,9 @@ type ButtonLinkProps = ButtonStyleProps &
     Component?: React.ElementType
   } & LinkAdapterPropsOverrides
 
+/**
+ * See [ButtonLink docs](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-button--docs#links)
+ */
 const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
   ({ children, Component, ...props }: ButtonLinkProps, ref) => {
     return (
@@ -381,7 +384,11 @@ const actionStyles = (size: ButtonSize) => {
 
 /**
  * A button that should contain a remixicon icon and nothing else.
- * For a variant that functions as a link, see ActionButtonLink.
+ * See [ActionButton docs](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-actionbutton--docs).
+ *
+ * See also:
+ * - [ActionButtonLink](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-button--docs#links)
+ * - [Button](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-button--docs) for text buttons
  */
 const ActionButton = styled(
   React.forwardRef<HTMLButtonElement, ActionButtonProps>((props, ref) => (
@@ -401,6 +408,9 @@ type ActionButtonLinkProps = ActionButtonStyleProps &
     Component?: React.ElementType
   } & LinkAdapterPropsOverrides
 
+/**
+ * See [ActionButtonLink docs](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-actionbutton--docs#links)
+ */
 const ActionButtonLink = ActionButton.withComponent(
   ({ Component, ...props }: ButtonLinkProps) => {
     return <LinkStyled Component={Component} {...props} />

src/components/ThemeProvider/ThemeProvider.stories.tsx

@@ -51,23 +51,44 @@ type Story = StoryObj<typeof ThemeProvider>
  *
  * In general, most useful theme properties are exposed on `theme.custom`. (Root
  * `theme` properties are used internally by MUI.) See typescript definitions
- * for more information.
+ * for more information about `theme.custom`.
+ *
+ * ## Further Customized Theme with `createTheme`
+ * Consuming applications can customize `smoot-design`'s default theme by creating
+ * a theme instance with `createTheme` and passing it to `ThemeProvider`:
+ *
+ * ```tsx
+ * const customTheme = createTheme({...})
+ *
+ * <ThemeProvider theme={customTheme}>
+ *   {children}
+ * </ThemeProvider>
+ * ```
+ *
  *
  * ### Custom Link Adapter
  * One particularly notable property is `theme.custom.LinkAdapter`. Some `smoot-design`
  * components render links. These links are native anchor tags by default. In
  * order to use these components with custom routing libraries (e.g. `react-router`
- * or `next/link`), you can provide a custom link adapter. Link components wills
+ * or `next/link`), you can provide a custom link adapter.
  *
- * As an example, `ButtonLink` will:
+ * Components such as `ButtonLink` will:
  *   - use `Component` on `ButtonLink` if specified (`<ButtonLink Component={Link} />`)
  *   - else, use `theme.custom.LinkAdapter` if specified,
  *   - else, use `a` tag.
  *
- * If you provide a custom `LinkAdapter` and need **aditional** props, you can
- * use [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to add the custom props to relevant
- * components. For example, if using `next/link`
+ * For example, to use `next/link` as the default link implementation:
+ *
+ * ```tsx
+ * import Link from "next/link"
+ * const theme = createTheme({ LinkAdapter: Link })
  * ```
+ *
+ * You can use [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)
+ * to add the custom props to relevant components. For example, to expose
+ * `next/link`'s `scroll` prop on `ButtonLink`:
+ *
+ * ```ts
  * // Add scroll prop to all components using LinkAdapter
  * declare module "@mitodl/smoot-design" {
  *   interface LinkAdapterPropsOverrides {

src/components/ThemeProvider/ThemeProvider.tsx

@@ -98,6 +98,12 @@ type ExtendedTheme = Theme & {
   custom: CustomTheme
 }
 
+/**
+ * Create a customized Smoot Design theme for use with `ThemeProvider`.
+ *
+ * See [ThemeProvider Docs](https://mitodl.github.io/smoot-design/?path=/docs/smoot-design-themeprovider--docs#further-customized-theme-with-createtheme)
+ * for more.
+ */
 const createTheme = (options?: {
   custom: Partial<ThemeOptions["custom"]>
 }): ExtendedTheme =>
@@ -116,6 +122,11 @@ type ThemeProviderProps = {
   theme?: Theme
 }
 
+/**
+ *
+ * @param param0
+ * @returns
+ */
 const ThemeProvider: React.FC<ThemeProviderProps> = ({
   children,
   theme = defaultTheme,