From 510315ef315c8e7881f59b385af5f577773ac05e Mon Sep 17 00:00:00 2001 From: cassie spain <58054751+dreamwasp@users.noreply.github.com> Date: Mon, 25 Nov 2024 16:45:23 -0500 Subject: [PATCH] typography + meta (#2975) * create foundations + layout stories * start foundations * start retooling componentheader * component header tweak * start restructure of header components * TOC + Theme working, need DataTable + code background color * working on color mode - need to fix text color * revert test * Theme page sorted, need to fix ColorMode * colormode sorted * colormode sorted * start type fix + what to do about blocks * LayoutGrid + content Container * LayoutGrid done * start flexbox, need to look into sandbox stuff * gridbox + flexbox are good, just need to tweak * tweaks to headers * lots of style tweaks + deduplications * fix typograpth, need to fix color mode switches * start on system stories * unify shared elements * add variance + fix tables * more tweaks to status * design tweaks * add hub * more tweaks * rename DataTable * clean up of default * typography + meta stories * add anchor story * start text + hiddentext * text done * started snippet changes * fixed code snippets * meta and sorted done?" * renamed + sorting * more kenny edits * more kenny edits + other new tab for links * the last of it --- .vscode/stories.code-snippets | 171 +++++++----- .../components/Elements/Callout.tsx | 9 + .../components/Elements/Markdown.tsx | 4 +- .../components/Headers/ComponentHeader.tsx | 1 - .../.storybook/components/index.tsx | 1 + packages/styleguide/.storybook/preview.ts | 19 +- packages/styleguide/src/lib/Layouts/About.mdx | 6 +- packages/styleguide/src/lib/Meta/About.mdx | 40 +++ .../src/lib/Meta/Best Practices.mdx | 247 ++++++++++++++++++ packages/styleguide/src/lib/Meta/Brand.mdx | 16 ++ .../styleguide/src/lib/Meta/Contributing.mdx | 92 +++++++ packages/styleguide/src/lib/Meta/FAQs.mdx | 58 ++++ packages/styleguide/src/lib/Meta/Stories.mdx | 169 ++++++++++++ .../styleguide/src/lib/Typography/About.mdx | 44 ++++ .../lib/Typography/Anchor/Anchor.examples.tsx | 116 ++++++++ .../src/lib/Typography/Anchor/Anchor.mdx | 110 ++++++++ .../lib/Typography/Anchor/Anchor.stories.tsx | 87 ++++++ .../lib/Typography/HiddenText/HiddenText.mdx | 36 +++ .../HiddenText/HiddenText.stories.tsx | 14 + .../src/lib/Typography/Text/Text.mdx | 111 ++++++++ .../src/lib/Typography/Text/Text.stories.tsx | 160 ++++++++++++ .../src/lib/Typography/Text/tables.tsx | 21 ++ .../src/static/typography/anchor.png | Bin 0 -> 8360 bytes 23 files changed, 1466 insertions(+), 66 deletions(-) create mode 100644 packages/styleguide/.storybook/components/Elements/Callout.tsx create mode 100644 packages/styleguide/src/lib/Meta/About.mdx create mode 100644 packages/styleguide/src/lib/Meta/Best Practices.mdx create mode 100644 packages/styleguide/src/lib/Meta/Brand.mdx create mode 100644 packages/styleguide/src/lib/Meta/Contributing.mdx create mode 100644 packages/styleguide/src/lib/Meta/FAQs.mdx create mode 100644 packages/styleguide/src/lib/Meta/Stories.mdx create mode 100644 packages/styleguide/src/lib/Typography/About.mdx create mode 100644 packages/styleguide/src/lib/Typography/Anchor/Anchor.examples.tsx create mode 100644 packages/styleguide/src/lib/Typography/Anchor/Anchor.mdx create mode 100644 packages/styleguide/src/lib/Typography/Anchor/Anchor.stories.tsx create mode 100644 packages/styleguide/src/lib/Typography/HiddenText/HiddenText.mdx create mode 100644 packages/styleguide/src/lib/Typography/HiddenText/HiddenText.stories.tsx create mode 100644 packages/styleguide/src/lib/Typography/Text/Text.mdx create mode 100644 packages/styleguide/src/lib/Typography/Text/Text.stories.tsx create mode 100644 packages/styleguide/src/lib/Typography/Text/tables.tsx create mode 100644 packages/styleguide/src/static/typography/anchor.png diff --git a/.vscode/stories.code-snippets b/.vscode/stories.code-snippets index be682ee3d1..da25ae07cd 100644 --- a/.vscode/stories.code-snippets +++ b/.vscode/stories.code-snippets @@ -1,86 +1,137 @@ { - "Component Story": { - "prefix": "component-story", + "Component Doc": { + "prefix": "component-doc", "body": [ - "import { $1 } from '@codecademy/$2';", - "import title from '@codecademy/macros/lib/title.macro';", - "import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';", - "import { PropsTable } from '@codecademy/storybook-addon-variance';", + "import { Canvas, Controls, Meta } from '@storybook/blocks';", + "", + "import { ComponentHeader } from '~styleguide/blocks';", + "", + "import * as $1Stories from './$1.stories';", + "", + "export const parameters = {", + "subtitle: `Template component`,", + "design: {", + "type: 'figma',", + "url: 'https: //www.figma.com/file/XXX',", + " },", + "status: 'current',", + "source: {", + "repo: '$2',", + "// this is easy to find by right clicking on the file in VSCode and clicking 'Copy Remote File Url From...' and the selecting 'main' or amending the url path below like so: https://github.com/Codecademy/gamut/blob/main/packages/${2}/src/file/location", + "githubLink:", + "'https: //github.com/Codecademy/gamut/blob/main/packages/gamut/src/Logo',", + " },", + "};", + "", + "", + "", + "", + "## Usage", + "", + "Use $1 to [what it should be used for]", + "", + "### Best practices:", + "", + "- [recommendation / best practice for implementation]", + "- [recommendation / best practice for implementation]", + "", + "When NOT to use", + "", + "- [use case]- for [describe the use case], use the [similar component] component.", + "- [use case]- for [describe the use case], use the [similar component] component", + "", + "## Anatomy", + "", + "[Insert image exported from Figma]", + "", + "1. [Element name]", + "- [description including available options and ux writing if relevant]", "", - "", + "## Variants", "", - "`$1` component summary goes here", + "### [Variant 1 name]", "", - "## Design Principles", + "Use the [variant 1 name] to [what it should be used for]", "", - "Design Principles summary", + "", "", - "## Usage Guidelines", + "## Playground", "", - "Usage summary", + "If you are using a story named 'Default', you can forgo the `of` prop.", "", - "## Code Playground", + "", "", - "", - " ", - " {(args) => <$1 {...args} />}", - " ", - "", + "", "", - "" + "## Accessibility considerations", + "", + "- [Accessibility guidance]", + "", + "## UX writing", + "", + "- [content]", + " - [guidance]", + " - [guidance]" ], - "description": "Default Component Story Structure." + "description": "Default Component Doc Structure." }, "Table of Contents Story": { "prefix": "toc-story", "body": [ - "import title from '@codecademy/macros/lib/title.macro';", - "import { Meta } from '@storybook/addon-docs/blocks';", + "import { Meta } from '@storybook/blocks';", + "import { AboutHeader, TableOfContents } from '~styleguide/blocks';", + "", + "export const parameters = {", + " id: '$1',", + " title: '$1/About',", + " subtitle: '$2',", + " }", "", - "import { TableOfContents } from '~styleguide/blocks';", + "", "", - "", + "", "", - "" + "Foundations make up the smallest scale design values that comprise a design system. Sometimes referred to elsewhere as "tokens", they are the abstract units that comprise and stitch together our atoms, molecules, and organisms.", + "", + "" ], "description": "TOC Story Structure." }, - "Canvas Block": { - "prefix": "canvas-block", - "body": [ - "", - " ", - " {(args) => <$2 {...args} />}", - " ", - "" - ], - "description": "A single story block wrapped in a canvas" - }, - "Story Block": { - "prefix": "story-block", + "Component Story": { + "prefix": "component-story", "body": [ - " ", - " {(args) => <$2 {...args} />}", - " " + "import { $1 } from '@codecademy/gamut';", + "import type { Meta, StoryObj } from '@storybook/react';", + "", + "const meta: Meta = {", + " component: $1,", + " args: {},", + "};", + "", + "export default meta;", + "type Story = StoryObj;", + "", + "export const Default: Story = {", + " args: {", + " children: 'Test'", + " },", + "};", + "", + "export const Secondary: Story = {", + " args: {", + " children: 'Test again',", + " variant: 'secondary'", + " }", + "};" ], - "description": "A single story block without a canvas" + "description": "Default TSX story structure." } } diff --git a/packages/styleguide/.storybook/components/Elements/Callout.tsx b/packages/styleguide/.storybook/components/Elements/Callout.tsx new file mode 100644 index 0000000000..f33b94df76 --- /dev/null +++ b/packages/styleguide/.storybook/components/Elements/Callout.tsx @@ -0,0 +1,9 @@ +import { Alert } from '@codecademy/gamut'; + +export const Callout: React.FC<{ text: string }> = ({ text }) => { + return ( + + {text} + + ); +}; diff --git a/packages/styleguide/.storybook/components/Elements/Markdown.tsx b/packages/styleguide/.storybook/components/Elements/Markdown.tsx index 0a5de3cc23..3ecf29348e 100644 --- a/packages/styleguide/.storybook/components/Elements/Markdown.tsx +++ b/packages/styleguide/.storybook/components/Elements/Markdown.tsx @@ -24,7 +24,9 @@ export const Link: React.FC = ({ ref, id, variant, ...props }) => { if (variant === 'area') { return ; } - return ; + return ( + + ); }; export const LinkTo = Link; diff --git a/packages/styleguide/.storybook/components/Headers/ComponentHeader.tsx b/packages/styleguide/.storybook/components/Headers/ComponentHeader.tsx index 6dccb7a0d3..9f080192b6 100644 --- a/packages/styleguide/.storybook/components/Headers/ComponentHeader.tsx +++ b/packages/styleguide/.storybook/components/Headers/ComponentHeader.tsx @@ -5,7 +5,6 @@ import { InfoTip, Text, } from '@codecademy/gamut'; -import { Background } from '@codecademy/gamut-styles'; import { Figma } from '@storybook/addon-designs/blocks'; import { Title } from '@storybook/blocks'; import * as React from 'react'; diff --git a/packages/styleguide/.storybook/components/index.tsx b/packages/styleguide/.storybook/components/index.tsx index 008fae063a..a5c61b29fb 100644 --- a/packages/styleguide/.storybook/components/index.tsx +++ b/packages/styleguide/.storybook/components/index.tsx @@ -1,6 +1,7 @@ export * from './ImageWrapper'; export * from './TokenTable'; export * from './Headers'; +export * from './Elements/Callout'; export * from './Elements/Markdown'; export * from './Scales/ColorScale'; export * from './Navigation/TableOfContents'; diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index b4556eab63..31d80937ff 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -7,13 +7,28 @@ import { DocsContainer } from './components/Elements/DocsContainer'; const preview: Preview = { parameters: { + backgrounds: { + disable: true, + }, docs: { container: DocsContainer, theme: theme, toc: { headingSelector: 'h1, h2, h3' }, }, - backgrounds: { - disable: true, + options: { + storySort: { + method: 'configure', + includeNames: true, + order: [ + 'Meta', + ['About', 'Best Practices', 'Contributing', 'FAQs', 'Stories'], + 'Foundations', + 'Layouts', + 'Typography', + 'Atoms', + '*', + ], + }, }, viewport: { defaultViewport: 'responsive', diff --git a/packages/styleguide/src/lib/Layouts/About.mdx b/packages/styleguide/src/lib/Layouts/About.mdx index 5313fa35ed..4fc6ed7bf3 100644 --- a/packages/styleguide/src/lib/Layouts/About.mdx +++ b/packages/styleguide/src/lib/Layouts/About.mdx @@ -9,7 +9,7 @@ export const parameters = { 'Layouts are basic building blocks to help you construct layouts on the page via configuration', }; - + @@ -21,6 +21,7 @@ Pure sizing and padding containers. These position our elements on pages in stan id: 'Layouts/Boxes/About', subtitle: 'Flexible container component with all system props available.', title: 'Boxes', + status: 'current', }, { id: 'Layouts/ContentContainer', @@ -35,5 +36,6 @@ Pure sizing and padding containers. These position our elements on pages in stan status: 'current', title: 'LayoutGrid', }, - ]} + +]} /> diff --git a/packages/styleguide/src/lib/Meta/About.mdx b/packages/styleguide/src/lib/Meta/About.mdx new file mode 100644 index 0000000000..67054a34f6 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/About.mdx @@ -0,0 +1,40 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, TableOfContents } from '~styleguide/blocks'; + +export const parameters = { + id: 'Meta', + title: 'Meta', + subtitle: + 'Documentation and associated links explaining our in-progress approach to a design system.', +}; + + + + + + diff --git a/packages/styleguide/src/lib/Meta/Best Practices.mdx b/packages/styleguide/src/lib/Meta/Best Practices.mdx new file mode 100644 index 0000000000..f02e19a473 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Best Practices.mdx @@ -0,0 +1,247 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, Callout } from '~styleguide/blocks'; + +export const parameters = { + id: 'Best Practices', + title: 'Best Practices', + subtitle: 'Current best practices for using the Gamut Design System', + status: 'current', +}; + + + + + +For best practices for writing for specific components, like alerts, errors, or confirmation dialogs, check out the individual component pages. + +# Variants + ColorMode + +The way we access design tokens is becoming increasingly important as we move away from a single theme and towards a system of themes. The best way to access design tokens is through our semantic colors, which are are tied intrinsically to ColorModes. This means that when you use a semantic color, you are guaranteed to get the right color for the right theme. Using variants and and its related utilities will also guarantee you have access to the right tokens, typings, and _state_ going forward. It is also [safer](https://gamut.codecademy.com/?path=/docs/foundations-system-compose--page)! + +Think of our semantic color names as a variable referencing _what the primary use of the color is within each color mode_. For example - an icon set to the `text` color will match _the primary color of text within that color mode._ + +For specific semantic name to color, please see the [ColorMode](https://gamut.codecademy.com/?path=/docs/foundations-colormode--page) documentation. + +### Use the utility functions from `gamut-styles` with ColorMode semantic color names + shorthands + +```tsx +import { css, states, variant } from '@codecademy/gamut-styles'; +import styled from '@emotion/styled'; + +// Single value +const Box = styled.div(css({ p: 4 })); + +// Mutiple values +const OtherCoolThing = styled.div(css({ color: 'primary', p: 4 })); + +// Need some variants? +const Anchor = styled.a( + variant({ + base: { p: 4 }, + defaultVariant: 'interface', + variants: { + interface: { + color: 'text', + '&:hover': { + color: 'text-accent', + }, + }, + inline: { + color: 'primary', + '&:hover': { + color: 'secondary', + }, + }, + }, + }) +); + +// Need some boolean states? +const UtilityBox = styled.div( + states({ + base: { mx: 4, my: 8, p: 16 }, + disabled: { + bg: 'background-disabled', + color: 'text-disabled', + }, + center: { + alignItems: 'center', + justifyContent: 'center', + }, + }) +); + +; +``` + + + +```tsx +import { states } from '@codecademy/gamut-styles'; +import { StyleProps } from '@codecademy/variance'; +import styled from '@emotion/styled'; +import React from 'react'; + +const someWrapperStates = states({ + absolute: { position: 'absolute', left: 'calc(50% - 85px)' }, + danger: { color: 'text', bg: 'danger' }, +}); + +const SomeWrapper = styled.div(someWrapperStates); + +export interface CoolNumberComponentProps + extends StyleProps { + coolNumber: number; + anotherCoolNumber: number; +} + +export const CoolNumberComponent: React.FC = ({ + coolNumber, + anotherCoolNumber, + ...rest //where your state props are! +}) => ; +``` + +# System props + +System props are a core part of our new approach to dynamic and customized styling. Where writing custom styles is painful, system props are here to make it painless. + +```tsx +import { Box } from '@codecademy/gamut'; + +const MyContainer = ({ children }) => ( + {children} +); + +const MyOtherContainer = ({ children }) => ( + + {children} + +); +``` + +**Intellisense + Typesafety** - Many system props are tied to specific design token scales. You can be sure that you are using the correct tokens between contexts. All props will autosuggest possible values for the scale that you are in. + +**Responsive Syntax** - [**Docs**](https://gamut.codecademy.com/storybook/?path=/docs/foundations-system-responsive-properties--page) All system props accept 2 responsive syntaxes for easily creating responsive layouts. System prop media queries are mobile first (Greater Than or Equal To). + +**The typings behind the scenes:** + +```tsx +type MediaQueryMap = { + _?: T; + xs?: T; + sm?: T; + md?: T; + lg?: T; + xl?: T; +}; + +type MediaQueryArray = [ + T?, // base + T?, // xs + T?, // sm + T?, // md + T?, // lg + T? // xl +]; + +type SystemProp = T | MediaQueryMap | MediaQueryArray; +``` + +**Usage:** + +```tsx +import { Box } from '@codecademy/gamut'; + +// Object Syntax + + +// Array Syntax + +``` + + + +## Real-world use cases + +**Mobile / Desktop specific content** + +```tsx +import { Box } from '@codecademy/gamut'; + +const App = () => ( +
+

Title

+ Desktop Only Content + Mobile Only Content +
+); +``` + +**Adaptive Layouts** - 3 columns ⇒ 2 columns + +```tsx +import { GridBox } from '@codecademy/gamut'; + +const SomeCoolLayout = ({ children }) => ( + + {children} + +); +``` + +**Design Token Access** - Responsively accessing tokens by key. + +```tsx +const CardLikeThing = ({ children }) => ( + + {children} + +); + +const Content = ({ children }) => ( + {children} +); +``` + +# ❌ Nested selectors + +Nested selectors can cause a huge amount of side effects unwittingly and make it very hard to maintain consistent behavior while making updates. We politely ask (and will shortly lint) that you refrain from using: + +- **Tag Selectors** - `*` `div` `p` `span` +- **Component Selectors (From Gamut)** - EG: `Box` + +```tsx +//❌ Don't do this❌ +const App = styled.main` + * { + box-sizing: content-box; + } +`; + +//❌ Don't do this❌ +const App = styled.main` + display: flex; + ${Box} { + align-self: start; + } +`; + +// ✅ Do this ✅ +const App = ({ children }) => ( + + {children} + +``` diff --git a/packages/styleguide/src/lib/Meta/Brand.mdx b/packages/styleguide/src/lib/Meta/Brand.mdx new file mode 100644 index 0000000000..eb97255c77 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Brand.mdx @@ -0,0 +1,16 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Brand', + title: 'Brand', + subtitle: `Codecademy internal and branded components`, + status: 'static', +}; + + + + + +The [Brand Library](https://brand-storybook.codecademy.com/) is a subset of assets, components, and themes intended for branded experiences and internal use. If you have any questions about Brand, feel free to reach out at #gamut-team on Slack. diff --git a/packages/styleguide/src/lib/Meta/Contributing.mdx b/packages/styleguide/src/lib/Meta/Contributing.mdx new file mode 100644 index 0000000000..6099e63ad0 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Contributing.mdx @@ -0,0 +1,92 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, Callout, LinkTo } from '~styleguide/blocks'; + +export const parameters = { + id: 'Contributing', + title: 'Contributing', + subtitle: `Thanks so much for being interested in contributing to Gamut! +We love working with Codecademy employees across all our teams.`, + status: 'static', +}; + + + + + +## Prework + +We track planned work for Gamut components in the [Gamut Board](https://skillsoftdev.atlassian.net/jira/software/projects/GM/boards/784) on JIRA. + +- If there's a ticket there you want to take on, send a Slack to #gamut-team or come to Gamut Office hours and lets talk about it! +- If the work you'd like to do isn't captured in a JIRA ticket, talk to us and we can work with you to create that ticket. +- If you would like to make a request for work to be done, please discuss with us on Slack or during Gamut Office Hours. +- If you'd like to pitch a change to the design system, please attend Gamut Crit, come to Gamut Office Hours, or send a Slack message to #gamut-team. + +## Writing components + +### Component structure + +Create your component as an `index.tsx` file in a PascalCase-named folder within its package directory, such as `packages/gamut/src/ProgressBar/index.tsx`. +Consider saving this recommended format as an editor snippet: + +```tsx +import React from 'react'; + +export type MyComponentProps = { + /* ... */ +}; + +export const MyComponent: React.FC = ( + { + /* ... */ + } +) => { + // ... +}; +``` + +#### Props documentation + +With the exception of widespread, self-documenting props such as `onClick`, please include a sentence cased description of the prop's intent. +React props on the component will be picked up by Storybook and added to the component's documentation story. +We prefer these be full sentences. + +```ts +/** + * Number of lines to limit the message to. + */ +limit: number; +``` + +- If your comment purely restartes the name and type of variable, please either elaborate on it or remove the comment altogether. +- Consider starting comments for booleans with _"Whether "_. + +### Unit tests + +Your component should have unit tests in a `__tests__/MyComponent-test.tsx` file within its directory. +Use Enzyme's `mount` to test it. + +We generally try to unit test all component logic, with the exception of class names in components that contain other logic. + +### Stories + +All components must have Storybook stories showing their use. See Stories for documentation. + +## Pull requests + +Please fill out the pull request template, including links to the corresponding Abstract design and JIRA ticket. + + + +### Publishing updates + +If you know your PR has breaking changes in at least one downstream repository, such as the [codecademy-engineering/mono](https://github.com/codecademy-engineering/mono): + +1. Before merging it, create PRs in those downstream repositories using your PR's published alpha package versions +2. Verify those PRs work as expected and get them signed off normally +3. Merge your Gamut PR +4. Wait until the new Gamut package is published, then update the downstream repository PRs to use it +5. Merge and deploy those PRs as soon as possible + +If your PR contains breaking changes that might affect other users, please mention them in the `#frontend` Slack channel. diff --git a/packages/styleguide/src/lib/Meta/FAQs.mdx b/packages/styleguide/src/lib/Meta/FAQs.mdx new file mode 100644 index 0000000000..641e3c8f45 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/FAQs.mdx @@ -0,0 +1,58 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'FAQs', + title: 'FAQs', + subtitle: + "Please let us know if there are questions you'd like answered here!", + status: 'static', +}; + + + + + +## How can I contribute? + +Thanks for your interest! 🙌 + +We are prepared to accept contributions from Codecademy employees only at this time, but we are working on a process to accept contributions from the wider community. Watch this space! + +## To Gamut or not to Gamut? + +> When should we create a general component in Gamut instead of a specific one in another application? + +In general, we prefer Gamut components to be those that are commonly shared across multiple experiences in the monolith. +If something can be easily built from the existing primitives _without_ adding logic, we generally wouldn't make a special component for it. + +Some examples of things we'd generally include in Gamut are: + +- Common visually identifiable atoms, such as buttons or form inputs +- Atoms linked together with client logic, such as an Alert bar + +Some examples of things we generally wouldn't include are: + +- Customized atoms specially designed for a particular use case, such as promotional "cards" +- Groups of components that could be recreated easily, such as a particular button and grid combination + +Consider referencing other design systems such as [Fluent](https://www.microsoft.com/design/fluent) and [Material Design](https://material.io/design) to see what they choose to turn into generic components. + +### Implementation strategy? + +> Should we implement components in separate repositories or in Gamut? + +As general rules of thumb: + +1. If a component is being written for the first time or used for a second time: + + - If the designer thinks it might belong in Gamut, feel free to implement it in the separate repository + - Consider making its API simple and flexible _(e.g. passing props to it instead of hooking it up to Redux)_ + - If the designer doesn't intend for it to be in the design system, never mind Gamut + +2. If a component is being used for a third time or more, please discuss moving it to Gamut + +## What's going on with accessibility? + +Codecademy is committed to becoming [WCAG 2.1 accessible](https://www.w3.org/WAI/standards-guidelines/wcag), and technical accessibility is a must-have in our design system.Components added here are expected to be fully AA compliant. diff --git a/packages/styleguide/src/lib/Meta/Stories.mdx b/packages/styleguide/src/lib/Meta/Stories.mdx new file mode 100644 index 0000000000..ac1afa5d82 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Stories.mdx @@ -0,0 +1,169 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Stories', + title: 'Meta/Stories', + subtitle: 'Guidelines and tooling for writing Storybook stories and docs.', + status: 'static', +}; + + + + + +## Quick start + +We've provided a few helpful vscode snippets to help you get through boilerplate. To use these start to type these strings in your editor and pick the template and fill out the tab targets. + +- `component-story`: The default TSX story template. +- `component-doc`: The default component documentation template - each component should have a `.tsx` and `.mdx` file. +- `toc-story`: A simple template for a Table of Contents category page. + +## File structure and naming + +When you make a new story theres a few things to keep in mind: + +- The folder structure is indicative of our flavor of atomic design. +- The folder struture is identical to the storybook hierarchy generated. + +First find the right folder for your story in `packages/styleguide/stories` (e.g. `Atoms` | `Molecules` | `Organisms`). +Once you've found it create a new folder with two new files `#{COMPONENT_NAME}.stories.tsx` and `#{COMPONENT_NAME}.mdx`. You can also store examples or other associated utility files in this folder. + +In your new files you can use the above snippets to set up your component add: + +```tsx +// For ComponentName.stories.tsx + +import { ComponentName } from '@codecademy/gamut'; +import type { Meta, StoryObj } from '@storybook/react'; + +const meta: Meta = { + component: ComponentName, + args: { + variant: 'default', + }, +}; + +export default meta; +type Story = StoryObj; + +export const Default: Story = { + args: { + children: jpeg, + }, +}; + +export const Secondary: Story = { + args: { + children: 'Pro Content', + variant: 'secondary', + }, +}; +``` + +```tsx +// For ComponentName.mdx, more details in the component-doc code snippet + +import { Canvas, Controls, Meta } from '@storybook/blocks'; + +import { ComponentHeader } from '~styleguide/blocks'; + +import * as ComponentStories from './ComponentName.stories'; + +export const parameters = { + subtitle: `Template component`, + design: { + type: 'figma', + url: 'https://www.figma.com/file/XXX', + }, + status: 'current', + source: { + repo: 'gamut', + // this is easy to find by right clicking on the file in VSCode and clicking "Copy Remote File Url From..." and the selecting 'main' or amending the url path below like so: https://github.com/Codecademy/gamut/blob/main/packages/${package}/src/file/location + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ComponentName', + }, +}; + + + + + +## Usage + +Etc... +``` + +## Story structure + +In our opinion, a good component story page consists of: + +1. **General Information:** Each component should define some key information on the `` component +2. **Flagship Story + Props:** A single default story showing the default state of the component with a connected props table right below it. +3. **Variation Stories:** Granular subsections that show the discrete varaitions of the component and describe their use cases +4. **Usage instructions and Guidelines:** A section that describes how to use the component should and shouldn't be used, and any guidelines that should be followed. + +### General information + +1. `subtitle`: What the component does, and what the component would typically be used for. +2. `source`: The source package of the component (e.g. `gamut` | `gamut-styles`) and a link to the corresponding code. +3. `status`: The health of the components API (e.g. `current` | `updating` | `deprecated` | `static`) +4. `design`: A link to the Figma file that is associated with the component. + +```tsx +import { Meta } from '@storybook/blocks'; + +import { ComponentHeader } from '~styleguide/blocks'; + +import * as AnchorStories from './Anchor.stories'; + +export const parameters = { + subtitle: `A clickable text element that navigates to another page, resource, or location on the same page.`, + design: { + type: 'figma', + url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=993-0', + }, + status: 'current', + source: { + repo: 'gamut', + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Anchor', + }, +}; + + + + + +``` + +### Flagship story + +The Flagship story for a component should be intended to give the reader a broad overview of its high-level functionality. Its `Canvas` should automatically display the story's code by setting the prop sourceState="shown". + +Try to include the major behaviors for the component that most readers would need to understand its uses. + +```tsx +## Playground + +//If your flagship story is named Default, you don't need to specify it for the Playground + + + +``` + +### Granular stories + +Each subsequent story should elaborate on an important behavioral feature of the component. +Try to show a single use of the behavior configurable with args. + +```tsx +## Variant Anchors + +A short description should go here, as well as any variant specific usage guidelines. + + + +``` diff --git a/packages/styleguide/src/lib/Typography/About.mdx b/packages/styleguide/src/lib/Typography/About.mdx new file mode 100644 index 0000000000..a098bc0d1b --- /dev/null +++ b/packages/styleguide/src/lib/Typography/About.mdx @@ -0,0 +1,44 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, TableOfContents } from '~styleguide/blocks'; + +export const parameters = { + id: 'Typography/About', + title: 'Typography', + subtitle: + 'These are basic primitives for displaying text components in configurable ways.', +}; + + + + + +Foundations make up the smallest scale design values that comprise a design system. +Sometimes referred to elsewhere as "tokens", they are the abstract units that comprise and stitch together our atoms, molecules, and organisms. + +