(garage week) styling and automated templates #5930
Conversation
|
📚 Branch Preview Links🔍 First Generation Visual Regression Test ResultsWhen a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:
Deployed to Azure Blob Storage: If the changes are expected, update the |
| - Disabled state | ||
| - Loading/indeterminate state | ||
| - Error state | ||
| - Selected/active state |
There was a problem hiding this comment.
| - Selected/active state | |
| - Selected/active state | |
| - Readonly state |
| - Default/normal state | ||
| - Disabled state | ||
| - Loading/indeterminate state | ||
| - Error state |
There was a problem hiding this comment.
| - Error state | |
| - Error state (valid or invalid) |
|
|
||
| Compare 2nd-gen against 1st-gen README.md for: | ||
|
|
||
| - [ ] Missing size options (xl is common) |
There was a problem hiding this comment.
Does next gen have an xl size option?
| - [ ] All size options documented with use cases | ||
| - [ ] All variant options documented with guidance | ||
| - [ ] Semantic variants have usage examples | ||
| - [ ] Non-semantic variants note 8-category limit |
There was a problem hiding this comment.
I didn't know about the 8-category limit. Where is this info?
There was a problem hiding this comment.
It’s just what cursor came up with. We can modify that.
nikkimk
left a comment
nikkimk
left a comment
There was a problem hiding this comment.
I love the addition of the cursor rules and the steps to simplify docs. I have added several suggestions to make sure we don't lose the quality and user experience of the documentation in the process of automating.
| ### Essential sections | ||
|
|
There was a problem hiding this comment.
| ### Essential sections | |
| ### Section order | |
| Main sections should follow the following order, skipping sections that are not applicable: | |
| 1. Installation | |
| 2. Anatomy | |
| 3. Options | |
| 4. States | |
| 5. Behaviors | |
| 6. Accessibility | |
| ### Essential sections |
There was a problem hiding this comment.
I think states should come before options but maybe we need to define these to be clear what we mean with those words
| 5. **ANATOMY STORIES section** with visual separator (if applicable) | ||
| 6. **STATES STORIES section** with visual separator (if applicable) | ||
| 7. **OPTIONS STORIES section** with visual separator | ||
| 8. **ACCESSIBILITY STORIES section** with visual separator |
There was a problem hiding this comment.
| 5. **ANATOMY STORIES section** with visual separator (if applicable) | |
| 6. **STATES STORIES section** with visual separator (if applicable) | |
| 7. **OPTIONS STORIES section** with visual separator | |
| 8. **ACCESSIBILITY STORIES section** with visual separator | |
| 5. **ANATOMY STORIES section** with visual separator | |
| 6. **OPTIONS STORIES section** with visual separator (if applicable) | |
| 7. **STATES STORIES section** with visual separator (if applicable) | |
| 8. **BEHAVIORS STORIES section** with visual separator (if applicable) | |
| 9. **ACCESSIBILITY STORIES section** with visual separator (if applicable) |
| ## States | ||
|
|
||
| <SpectrumStories tag="states" /> | ||
|
|
||
| ## Options | ||
|
|
||
| <SpectrumStories tag="options" /> |
There was a problem hiding this comment.
| ## States | |
| <SpectrumStories tag="states" /> | |
| ## Options | |
| <SpectrumStories tag="options" /> | |
| ## Options | |
| <SpectrumStories tag="options" /> | |
| ## States | |
| <SpectrumStories tag="states" /> | |
| ## Behaviors | |
| <SpectrumStories tag="behaviors" /> |
| // ────────────────────────── | ||
| // ANATOMY STORIES | ||
| // ────────────────────────── | ||
|
|
||
| // ────────────────────────── | ||
| // STATES STORIES | ||
| // ────────────────────────── | ||
|
|
||
| // ────────────────────────── | ||
| // OPTIONS STORIES | ||
| // ────────────────────────── |
There was a problem hiding this comment.
| // ────────────────────────── | |
| // ANATOMY STORIES | |
| // ────────────────────────── | |
| // ────────────────────────── | |
| // STATES STORIES | |
| // ────────────────────────── | |
| // ────────────────────────── | |
| // OPTIONS STORIES | |
| // ────────────────────────── | |
| // ────────────────────────── | |
| // ANATOMY STORIES | |
| // ────────────────────────── | |
| // ────────────────────────── | |
| // OPTIONS STORIES | |
| // ────────────────────────── | |
| // ────────────────────────── | |
| // STATES STORIES | |
| // ────────────────────────── | |
| // ────────────────────────── | |
| // BEHAVIORS STORIES | |
| // ────────────────────────── |
| ### States stories | ||
|
|
||
| Stories demonstrating different states (if applicable): | ||
|
|
||
| ```typescript | ||
| /** | ||
| * Description of this particular state. | ||
| */ | ||
| export const StateName: Story = { | ||
| render: (args) => html` | ||
| ${template({ ...args /* state example */ })} | ||
| `, | ||
| tags: ['states'], | ||
| args: {}, | ||
| }; | ||
| ``` | ||
|
|
||
| ### Options stories | ||
|
|
||
| Stories demonstrating variants, sizes, styles: | ||
|
|
||
| ```typescript | ||
| /** | ||
| * Description of this option/variant. | ||
| */ | ||
| export const OptionName: Story = { | ||
| render: () => html` | ||
| ${/* examples */} | ||
| `, | ||
| tags: ['options'], | ||
| }; | ||
| ``` |
There was a problem hiding this comment.
| ### States stories | |
| Stories demonstrating different states (if applicable): | |
| ```typescript | |
| /** | |
| * Description of this particular state. | |
| */ | |
| export const StateName: Story = { | |
| render: (args) => html` | |
| ${template({ ...args /* state example */ })} | |
| `, | |
| tags: ['states'], | |
| args: {}, | |
| }; | |
| ``` | |
| ### Options stories | |
| Stories demonstrating variants, sizes, styles: | |
| ```typescript | |
| /** | |
| * Description of this option/variant. | |
| */ | |
| export const OptionName: Story = { | |
| render: () => html` | |
| ${/* examples */} | |
| `, | |
| tags: ['options'], | |
| }; | |
| ``` | |
| ### Options stories | |
| Stories demonstrating variants, sizes, styles: | |
| ```typescript | |
| /** | |
| * Description of this option/variant. | |
| */ | |
| export const OptionName: Story = { | |
| render: () => html` | |
| ${/* examples */} | |
| `, | |
| tags: ['options'], | |
| }; | |
| ``` | |
| ### States stories | |
| Stories demonstrating different states (if applicable): | |
| ```typescript | |
| /** | |
| * Description of this particular state. | |
| */ | |
| export const StateName: Story = { | |
| render: (args) => html` | |
| ${template({ ...args /* state example */ })} | |
| `, | |
| tags: ['states'], | |
| args: {}, | |
| }; | |
| ``` | |
| ### Behaviors stories | |
| Stories demonstrating different behaviors (if applicable): | |
| ```typescript | |
| /** | |
| * Description of this particular behavior. | |
| */ | |
| export const StateName: Story = { | |
| render: (args) => html` | |
| ${template({ ...args /* behavior example */ })} | |
| `, | |
| tags: ['behaviors'], | |
| args: {}, | |
| }; | |
| ``` |
There was a problem hiding this comment.
Behaviors stories should include things like methods, events, interaction, or anything the component does automatically, like truncation or text wrapping.
| * Badges come in four sizes to fit various contexts: | ||
| */ | ||
| export const SemanticVariants: Story = { | ||
| export const Sizes: Story = { |
There was a problem hiding this comment.
The array mapping is showing up in the docs code snippet instead of the rendered HTML, so what if we try this?
| export const Sizes: Story = { | |
| const sizesTemplate = CONTAINER(Badge.VALID_SIZES.map( | |
| (size) => html` | |
| <swc-badge size=${size as BadgeSize} | |
| >${capitalize(size)}</swc-badge | |
| > | |
| ` | |
| )); | |
| export const Sizes: Story = { |
| export const SemanticVariants: Story = { | ||
| export const Sizes: Story = { | ||
| render: () => | ||
| CONTAINER( |
There was a problem hiding this comment.
| CONTAINER( | |
| sizesTemplate |
| Badge.VALID_SIZES.map( | ||
| (size) => html` | ||
| <swc-badge size=${size as BadgeSize} | ||
| >${capitalize(size)}</swc-badge | ||
| > | ||
| ` | ||
| ) | ||
| ), |
There was a problem hiding this comment.
| Badge.VALID_SIZES.map( | |
| (size) => html` | |
| <swc-badge size=${size as BadgeSize} | |
| >${capitalize(size)}</swc-badge | |
| > | |
| ` | |
| ) | |
| ), |
| * When the text is too long for the horizontal space available, it wraps to form another line. | ||
| */ | ||
| export const Sizes: Story = { | ||
| export const TextWrapping: Story = { |
There was a problem hiding this comment.
Since this is automatically done and not something consumers can control with the API, it should really move to behaviors.
| /** | ||
| * When a badge's label is too long for the available horizontal space, it wraps to form another line. Text wrapping can be enforced when a `max-inline-size` is applied to the badge. | ||
| */ | ||
| export const Textwrapping: Story = { |
There was a problem hiding this comment.
Since this is automatically done and not something consumers can control with the API, it should really move to behaviors.
| * - Secondary element description (optional) | ||
| * - Additional elements | ||
| * | ||
| * Components can contain X, Y, or both. |
There was a problem hiding this comment.
It's not clear to me what X and Y are here.
| - [ ] States section if component has states | ||
| - [ ] Disabled state documented if supported | ||
| - [ ] Accessibility Features section with numbered list | ||
| - [ ] Accessibility Best Practices section with bullet points |
There was a problem hiding this comment.
Should these be Accessibility features and Accessibility best practices?
| @@ -0,0 +1,9 @@ | |||
| # Installing local extensions in Cursor | |||
|
|
|||
| The extensions in this directory are not available in Cursor but are in VSCode. The `vsix` file can be uploaded to Cursor locally to install the extension for usage. | |||
There was a problem hiding this comment.
| The extensions in this directory are not available in Cursor but are in VSCode. The `vsix` file can be uploaded to Cursor locally to install the extension for usage. | |
| The extensions in this directory are not available in Cursor but are in VSCode. The `vsix` file can be imported into Cursor. |
|
|
||
| 1. Go to cursor, hit Cmd + Shift + P | ||
| 2. Search for “Extensions: Install from VSIX…” | ||
| 3. Select the extension file from this directory and download |
There was a problem hiding this comment.
| 3. Select the extension file from this directory and download | |
| 3. Select the extension file from this directory |
| }, | ||
| }, | ||
| tags: ['!autodocs', '!dev'], | ||
| tags: ['!autodocs', '!dev'], // We only want the playground stories to be visible in the docs and sidenav. Since a majority of our stories are tagged with '!autodocs' and '!dev', we set those tags globally. We can opt in to visibility by adding the 'autodocs' or 'dev' tags to individual stories. |
Description
Motivation and context
Related issue(s)
Screenshots (if appropriate)
Author's checklist
Reviewer's checklist
patch,minor, ormajorfeaturesManual review test cases
Descriptive Test Statement
Descriptive Test Statement
Device review