Skip to content

Commit 929c7f5

Browse files
authored
stories: link to contributing guide (#15825)
Fix DE-185
1 parent 7a47ffe commit 929c7f5

File tree

1 file changed

+4
-111
lines changed

1 file changed

+4
-111
lines changed

develop-docs/frontend/component-library.mdx

Lines changed: 4 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -23,123 +23,16 @@ Stories is a custom docs framework served under the `/stories` path inside the m
2323
- **Dev Access**<br />
2424
Whether you are using `pnpm dev-ui` to start a development server, or `sentry devserver` to spin up all the services locally, you can access Stories by logging in and changing the path from `/issues/` (the default landing page) to `/stories/`.
2525

26+
## Contributing to Stories
27+
28+
For information on how to contribute to Stories, please see the [Contributing](https://sentry.sentry.io/stories/core/contributing/) section of the Stories documentation.
29+
2630
## Ownership
2731

2832
Stories for core components are owned by the Design Engineering team. Stories for general components are not nessicarily maintained by the original author or team of that component—if you are reading a story and notice a mistake or omission, consider it an opportunity to leave the docs in better shape than you found them!
2933

3034
The Design Engineering team is always available in the `#discuss-design-engineering` channel on Slack for questions or general feedback.
3135

32-
## Creating new Stories
33-
34-
### Using `.mdx`
35-
36-
The easiest way to document a single component is to create an `.mdx` file next to the component. For a new `myButton` component, the file can be named `index.mdx` or `myButton.mdx`.
37-
38-
```
39-
components/
40-
└── myButton/
41-
├── index.tsx
42-
└── index.mdx
43-
```
44-
45-
The file can include the following frontmatter fields.
46-
47-
```yaml
48-
---
49-
title: My Button
50-
description: MyButton is a clickable element that triggers an action.
51-
source: 'sentry/components/myButton'
52-
# optionally include links to figma, js, and a11y resources:
53-
resources:
54-
figma: https://www.figma.com/design/...
55-
js: https://github.com/getsentry/sentry/...
56-
a11y:
57-
WCAG 1.4.3: https://www.w3.org/TR/WCAG22/#contrast-minimum
58-
WAI-ARIA Button Practices: https://www.w3.org/WAI/ARIA/apg/patterns/button/
59-
---
60-
```
61-
62-
Components can include autogenerated API documentation using our [custom type-loader](https://github.com/getsentry/sentry/blob/master/static/app/stories/type-loader.ts) and exporting an object named `types`. The [inline loader syntax](https://rspack.rs/api/loader-api/inline) is weird, but it works.
63-
64-
```mdx
65-
import APIReference from '!!type-loader!sentry/components/myButton/index';
66-
67-
export const types = {MyButton: APIReference.MyButton};
68-
```
69-
70-
For a good example, see the [button.mdx](https://github.com/getsentry/sentry/blob/master/static/app/components/core/button/index.mdx?plain=1) file.
71-
72-
### Helper Components
73-
74-
There are some common helper components available to make common patterns in stories easier to implement.
75-
76-
```mdx
77-
import * as Storybook from 'sentry/stories';
78-
```
79-
80-
- [`<Demo />`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/demo.tsx)<br />
81-
Renders a preview frame around a component.
82-
83-
- [`<JSXNode />`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/jsxNode.tsx)<br />
84-
Render a formatted JSX component name and some properties.<br />
85-
```tsx
86-
return <JSXNode name="IconFire" props={{color: 'red400', size: 'sm'}} />;
87-
88-
// will render as <code>&lt;IconFire<br/>color="red"<br/>size="sm" \:gt;</code>
89-
```
90-
91-
- [`<JSXProperty />`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/jsxProperty.tsx)
92-
Render a formatted JSX property name & value.<br />
93-
```tsx
94-
return <JSXProperty name="disabled" value={false} />;
95-
96-
// will render as `<code>size={false}</code>`
97-
```
98-
99-
- [`<SideBySide>{children}</SideBySide>`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/sideBySide.tsx)<br />
100-
A shortcut for `display: flex;` to render multiple items in a row, wrapping as needed
101-
```tsx
102-
return (
103-
<SideBySide>
104-
<Badge type="default">Default</Badge>
105-
<Badge type="alpha">Alpha</Badge>
106-
<Badge type="beta">Beta</Badge>
107-
</SideBySide>
108-
);
109-
```
110-
111-
- [`<SizingWindow />`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/sizingWindow.tsx)<br />
112-
A wrapper component to help demonstrate what the component looks like when the parent size is different or changing.<br />
113-
By default uses `display:flex; overflow: hidden;` which can test responsive components well. Can also be set to `display: block; overflow: auto;`.<br />
114-
```tsx
115-
<SizingWindow style={{height: '100px'}}>
116-
<LoadingTriangle />
117-
</SizingWindow>`
118-
```
119-
120-
- [`<Matrix />`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/matrix.tsx)<br />
121-
A helper to render multiple pairs of properties and values in a grid.
122-
For example, we can render all button `priority` values against all possible `size` values which results in a 4x5 matrix of outputs.
123-
```tsx
124-
<Matrix
125-
render={() => Button}
126-
propMatrix={{
127-
priority: ['default', 'primary'],
128-
size: ['md', 'sm'],
129-
}}
130-
selectedProps={['priority', 'size']}
131-
/>
132-
```
133-
134-
- [`<ThemeToggle />`](https://github.com/getsentry/sentry/blob/master/static/app/components/stories/themeToggle.tsx)<br />
135-
A wrapper component to isolate children from the current theme used on the page. Allows quickly toggling an example between <code>light</code>/<code>dark</code> without changing the whole screen (useful at night when you want most things in dark mode).<br/>
136-
Use this to emphasize that a component/image has been tested and works well in <code>light</code> or <code>dark</code> mode.
137-
```tsx
138-
<ThemeToggle>
139-
<LoadingTriangle />
140-
</ThemeToggle>
141-
```
142-
14336
## Improving Stories
14437

14538
All code for the stories framework is built and maintained by Sentry's Design Engineering team. However, this tool is for all of us, so contributions are welcome! If you have ideas to improve the experience of discovering, reading, writing, or organizing stories, please share in the `#discuss-design-engineering` channel on Slack.

0 commit comments

Comments
 (0)