docs(grid): updated with API docs and example #3136
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,6 +30,7 @@ guide to start building. | |
| <AnchorLink>Incorporating the shell</AnchorLink> | ||
| <AnchorLink>Alignments</AnchorLink> | ||
| <AnchorLink>Techniques</AnchorLink> | ||
| <AnchorLink>API</AnchorLink> | ||
| <AnchorLink>Resources</AnchorLink> | ||
|
|
||
| </AnchorLinks> | ||
|
|
@@ -1343,6 +1344,42 @@ Image size can change ratios when the breakpoint changes. | |
| </DoDont> | ||
| </DoDontRow> | ||
|
|
||
| ## API | ||
|
|
||
| There are many ways to make the 2x Grid work for your application using our API. | ||
| The example below illustrates removing visibility of a given component based on | ||
| the maximum width of the `md` breakpoint. Check out the table to learn more | ||
| about our API. | ||
|
|
||
| ```css | ||
| .component { | ||
| display: inline; | ||
|
|
||
| /* applies styles inside mixin on md breakpoint or below, like max-width */ | ||
| @include carbon--breakpoint-down('md') { | ||
| display: none; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| | Name | Description | Type | Default | | ||
| | :----------------------- | :---------------------------------------------------------------------------------- | :---------- | :------------ | | ||
| | `css-grid` | Generate the CSS for using the CSS Grid | `@mixin` | | | ||
| | `$prefix` | Specify the prefix used for CSS selectors | `String` | `'cds'` | | ||
| | `$flex-grid-columns` | Specify the number of columns for the flex grid | `Number` | `16` | | ||
| | `$grid-gutter` | Specify the gutter of the grid | `Number` | `32px (2rem)` | | ||
| | `$grid-gutter-condensed` | Specify the gutter of the condensed grid | `Number` | `1px` | | ||
| | `$grid-breakpoints` | Specify the breakpoints for the grid | `Map` | | | ||
| | `breakpoint-next` | Get the value of the next breakpoint | `@function` | | | ||
| | `breakpoint-prev` | Get the value of the previous breakpoint | `@function` | | | ||
| | `is-smallest-breakpoint` | Check to see if the given breakpoint is the smallest breakpoint | `@function` | | | ||
| | `is-largest-breakpoint` | Check to see if the given breakpoint is the largest breakpoint | `@function` | | | ||
| | `breakpoint-up` | Generate a media query from the width of the given breakpoint to infinity | `@mixin` | | | ||
| | `breakpoint-down` | Generate a media query that applies below the maximum width of the given breakpoint | `@mixin` | | | ||
| | `breakpoint-between` | Generate a media query for the range between the lower and upper breakpoints | `@mixin` | | | ||
| | `largest-breakpoint` | Generate a media query for the largest breakpoint | `@mixin` | | | ||
| | `breakpoint` | Generate a media query for a given breakpoint, alias of `breakpoint-up` | `@mixin` | | | ||
|
There was a problem hiding this comment. Could we instead link to the grid package Sass API docs? https://github.com/carbon-design-system/carbon/blob/main/packages/grid/docs/sass.md#api If we duplicate this here, one of them is bound to become out of date. I don't think we surface full Sass API information anywhere else on the website. There was a problem hiding this comment. I think we do have a resource tile that links to the package readme. I think there's a big need to surface these here as well. We tend to do this with all our elements stuff like spacing, motion sass - https://carbondesignsystem-fq9t0896o-carbon-design-system.vercel.app/guidelines/motion/code but we don't do anything for grid. We don't surface that code anywhere on our website. Totally get the issue about these becoming out of date though. I'm not sure of a workaround for that. How often do we make changes to the grid API? There was a problem hiding this comment. Ok, I think I may have found a middle ground. Let me know what you think. |
||
|
|
||
| ## Resources | ||
|
|
||
| <Row className="resource-card-group"> | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The adding of helper classes in carbon-design-system/carbon#11786 was intended to replace the need for this type of manual config. Should we just point them to those classes instead?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the grid mixins would still be needed for other use cases, no? Like if you wanted to change the layout or styles of something at mobile breakpoints (not necessarily just hide it). @tay1orjones but we should also add those classes and surface them here! I think surfacing all options is good.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great points all around. Let me do another rev where have both options listed, but do a little progressive disclosure to link out to our github docs so things don't get out of sync like Taylor mentions in his other comment.