-
Notifications
You must be signed in to change notification settings - Fork 67
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update most of Compiled documentation to reflect current recommendati…
…ons (#1688) * Update 'Writing CSS' and 'Installation', move some sections into new 'Deprecated features' section * Update CSS prop page and deprecated syntax page: - move template literals to deprecated page - discourage dynamic styles - move outdated composition syntax to deprecated page * Fix order of pages in Guides and API sections * Fix typo in JSX pragma * Update documentation for Compiled APIs * Deprecate styled and ClassNames * Merge CSS page into CSS prop * Update cssMap to use flat `@media` query syntax, not the nested one that DST will remove support for * Move details about the `jsx-pragma` ESLint rule to the "JSX pragma" section of the Installation page * Make imports alphabetical
- Loading branch information
Showing
14 changed files
with
352 additions
and
251 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,75 +1,41 @@ | ||
| --- | ||
| section: 5-API | ||
| order: 1 | ||
| name: CSS Prop | ||
| name: css prop | ||
| --- | ||
|
|
||
| import { | ||
| CssPropObj, | ||
| CssPropString, | ||
| CssPropDynamic, | ||
| CssPropCompositionCorrect, | ||
| CssPropCompositionIncorrect, | ||
| CssPropCompositionNoStyle, | ||
| CssPropConditionalRules, | ||
| } from '../examples/css-prop'; | ||
| import { CssPropConditionalRules, CssPropDynamic, CssPropObj } from '../examples/css-prop'; | ||
|
|
||
| # CSS Prop | ||
| # css prop | ||
|
|
||
| Style a JSX element, | ||
| enabled when a JSX pragma is defined and the JSX element also takes a `className` prop. | ||
| Using a `css` function call on a `css` prop is the preferred way to apply styles to a JSX element. This is enabled when a JSX pragma is defined, and the JSX element takes a `className` prop. | ||
|
|
||
| <CssPropObj /> | ||
|
|
||
| > **Don't worry about the pragma**<br /> | ||
| > For a streamlined developer experience install the `jsx-pragma` rule from the [ESLint plugin](/pkg-eslint-plugin) and never forget it again. | ||
| We use a syntax similar to Emotion's `css` prop, but we wrap the style object in a `css` function call. Using the `css` function call allows us to apply type checking, and it makes it clear that the styles should be applied by Compiled (and not a different CSS-in-JS library). | ||
|
|
||
| ## Template literal rules | ||
| > **Only use `css` with Compiled APIs**<br /> | ||
| > The return value of the `css` function call at runtime is `null` and can only be passed to the `css` prop, or used with other Compiled APIs. | ||
| Write your styles as a template literal. | ||
| Use the [`css`](/api-css) import for better syntax highlighting. | ||
| <CssPropObj /> | ||
|
|
||
| <CssPropString /> | ||
| ## Using composition to combine styles | ||
|
|
||
| Although template literal is supported, we recommend using object style instead of template literal. | ||
| Read [composition](/composition) for more information around composing styles together. | ||
|
|
||
| ## Conditional rules | ||
|
|
||
| Conditionally apply [CSS rules](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_is_structured#Selectors). | ||
| Conditionally apply [CSS rules](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_is_structured#Selectors) by passing an array to the `css` prop. The last styles applied in the array wins. | ||
|
|
||
| <CssPropConditionalRules /> | ||
|
|
||
| ## Dynamic declarations | ||
|
|
||
| Change a [CSS declaration](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_is_structured#Properties_and_values) at runtime, | ||
| powered by [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). | ||
|
|
||
| <CssPropDynamic /> | ||
|
|
||
| ## Composition gotchas | ||
|
|
||
| Compiled will try to generate the smallest amount of code possible. | ||
| When composing styles ensure to explicitly define both a `className` and `style` prop. | ||
| ## Dynamic styling and props | ||
|
|
||
| Here the `className` and `style` props are both defined so styling works correctly. | ||
| We no longer recommend passing dynamic styling or props to Compiled, as they can be tricky for other Atlassian tooling to statically analyse. | ||
|
|
||
| <CssPropCompositionCorrect /> | ||
| Instead, we recommend you: | ||
|
|
||
| The next few example show what happens if you don't do this. | ||
| - First, determine whether you truly need the styles to be dynamic. Many cases of dynamic styling can be rewritten as conditional rules or [`cssMap` usages](/api-cssmap). | ||
| - If you absolutely need to use dynamic styling, you can pass dynamic styling to the `style` prop. Check out the [UI Styling Standard](https://atlassian.design/components/eslint-plugin-ui-styling-standard/migration-guide) for more details. | ||
|
|
||
| ### Spread pops | ||
| In the past, this was how to write dynamic styles with Compiled: | ||
|
|
||
| The overflow `props` are spread onto the element so the composed styles are not applied. | ||
|
|
||
| Statically defining them fixes this. | ||
|
|
||
| <CssPropCompositionIncorrect /> | ||
|
|
||
| ### Missing style | ||
|
|
||
| The `style` prop is missing so the CSS variables used to power dynamic declarations aren't set. | ||
| In this case instead it receives the `body` color value instead of pink. | ||
|
|
||
| Statically defining the style prop fixes this. | ||
|
|
||
| <CssPropCompositionNoStyle /> | ||
| <CssPropDynamic /> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,9 @@ | ||
| --- | ||
| section: 5-API | ||
| order: 99 | ||
| name: CSS | ||
| order: 13 | ||
| name: '[Archived] CSS' | ||
| --- | ||
|
|
||
| # CSS | ||
|
|
||
| Define styles that can be statically typed and useable with other Compiled APIs. | ||
|
|
||
| > **Opaque styles**<br/> | ||
| > The return value of `css` at runtime is `null` and can only be used with other Compiled APIs. | ||
| ```jsx | ||
| const redText = css({ | ||
| color: 'red', | ||
| }); | ||
|
|
||
| <div css={redText} />; | ||
| ``` | ||
|
|
||
| Read [composition](/composition) for more information around composing styles together. | ||
| The contents of this page have been merged into the [css prop](/api-css-prop) documentation. Check it out! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,7 @@ | ||
| --- | ||
| section: 50-Guides | ||
| name: Atomic CSS | ||
| order: 99 | ||
| order: 20 | ||
| --- | ||
|
|
||
| # Atomic CSS | ||
|
|
||
Oops, something went wrong.