From d6160ea630001aa07721e64dcfd505d2add4c383 Mon Sep 17 00:00:00 2001 From: simurai Date: Mon, 24 Jan 2022 11:53:57 +0900 Subject: [PATCH] Docs updates (#1895) * Remove "Atom packages" * Remove Docset * Remove "Local development" * Remove "Table object" * Move Grid to utilities * Remove "Objects" * Rename nav (marketing) * Move marketing styles to their own section * Discourage floats * Update padding description --- docs/content/components/box.md | 2 +- docs/content/components/navigation.md | 2 +- docs/content/getting-started/contributing.md | 13 ++- docs/content/index.mdx | 4 +- docs/content/marketing/index.md | 6 ++ docs/content/objects/index.md | 6 -- docs/content/objects/table-object.md | 27 ------ docs/content/principles/index.md | 25 +---- docs/content/support/breakpoints.md | 2 +- docs/content/tools/atom-packages.md | 52 ---------- docs/content/tools/docset.md | 18 ---- docs/content/tools/linting.md | 8 +- docs/content/tools/local-primer.md | 96 ------------------- docs/content/utilities/flexbox.md | 2 +- docs/content/{objects => utilities}/grid.md | 42 ++++---- docs/content/utilities/layout.md | 12 ++- docs/content/utilities/margin.md | 2 +- docs/content/utilities/padding.md | 4 +- .../src/@primer/gatsby-theme-doctocat/nav.yml | 38 +++----- .../components/Layout/LayoutBeta.stories.jsx | 2 +- .../components/Layout/PageLayout.stories.jsx | 2 +- src/table-object/README.md | 25 ----- src/table-object/table-object.scss | 3 + vercel.json | 7 +- 24 files changed, 79 insertions(+), 321 deletions(-) create mode 100644 docs/content/marketing/index.md delete mode 100644 docs/content/objects/index.md delete mode 100644 docs/content/objects/table-object.md delete mode 100644 docs/content/tools/atom-packages.md delete mode 100644 docs/content/tools/docset.md delete mode 100644 docs/content/tools/local-primer.md rename docs/content/{objects => utilities}/grid.md (99%) delete mode 100644 src/table-object/README.md diff --git a/docs/content/components/box.md b/docs/content/components/box.md index fccfeb33..7f100aea 100644 --- a/docs/content/components/box.md +++ b/docs/content/components/box.md @@ -554,7 +554,7 @@ You can put forms in boxes. Often form submission buttons are aligned to the bot ``` -When a box is all by itself centered on a page you can use [column widths](/objects/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/utilities/typography) instead of the built in box title styles. +When a box is all by itself centered on a page you can use [column widths](/utilities/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/utilities/typography) instead of the built in box title styles. ```html live
diff --git a/docs/content/components/navigation.md b/docs/content/components/navigation.md index bf4a483f..c9d7ab68 100644 --- a/docs/content/components/navigation.md +++ b/docs/content/components/navigation.md @@ -205,7 +205,7 @@ Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNa ## Side Nav -The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **Side Nav elements have no default width or positioning**. We suggest using [column grid](../objects/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content. +The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **Side Nav elements have no default width or positioning**. We suggest using [column grid](../utilities/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content. - You can use a **border** if the parent element doesn't have it already. - Add `aria-current="page"` to show a link as selected. Selected button elements in tab-like UIs should instead have `aria-selected="true"`. diff --git a/docs/content/getting-started/contributing.md b/docs/content/getting-started/contributing.md index c510d6e5..b765d3f8 100644 --- a/docs/content/getting-started/contributing.md +++ b/docs/content/getting-started/contributing.md @@ -9,13 +9,13 @@ While this contributing guide is for GitHub employees, all contributions from th ### Components -[Components](/components) are frequently used visual patterns we've abstracted into a set of convenient styles, that would be otherwise difficult to achieve with utilities and layout objects. +[Components](/components) are frequently used visual patterns we've abstracted into a set of convenient styles, that would be otherwise difficult to achieve with utilities. Decisions to add new components are made on a case-by-case basis, with help from the GitHub Design Systems team. Some questions that we use to guide these decisions include: - How often is this pattern used across the site? -- Could these styles be achieved with existing components, objects, and utilities? -- If your design is difficult to compose with current styles, does this highlight problems with existing components (such as overly-specific components, or missing objects and utilities)? +- Could these styles be achieved with existing components and utilities? +- If your design is difficult to compose with current styles, does this highlight problems with existing components (such as overly-specific components, or missing utilities)? - Is this a totally new pattern or should it be an extension of an existing component? - How is this pattern being implemented currently - have you identified problems with it’s current implementation that can be improved with adding a new pattern? - Is the desire for this new pattern a side-effect of lacking documentation or misunderstanding of use with current styles? @@ -23,12 +23,11 @@ Decisions to add new components are made on a case-by-case basis, with help from - Is this something that would be better handled by other front-end code rather than CSS? - Every new addition of CSS means we ask our users to download a larger CSS file, and we increase the maintenance work of our CSS framework. Does the convenience of adding these new styles outweigh those costs? -### Objects and utilities +### Utilities -Many of the same questions can be applied to objects and utilities, however the purpose of these styles is different: +Many of the same questions can be applied to utilities, however the purpose of these styles is different: -- [Objects](/objects) aren't concerned with thematic styles. They are for common display and positioning styles we find in page layouts and common content types. -- [Utilities](/utilities) do one thing well and one thing only. These styles are immutable and therefore often use the `!important` tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions: +[Utilities](/utilities) do one thing well and one thing only. These styles are immutable and therefore often use the `!important` tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions: - How does this new utility fit within our existing set of utilities? If it is an addition to an existing set then it should follow the same naming convention. - Is it for a property that would likely need to be changed at different breakpoints? If so it may need responsive options. - If this style is part of a family of properties, do we need to consider adding the full set? Reasons for adding a full set could be that the other property values are often used, or that there would be a need to switch the property on and off (such as display or visibility). diff --git a/docs/content/index.mdx b/docs/content/index.mdx index 98f24c20..9012b25f 100644 --- a/docs/content/index.mdx +++ b/docs/content/index.mdx @@ -6,7 +6,6 @@ import {HeroLayout} from '@primer/gatsby-theme-doctocat' import {Grid, Box, Heading, Text, ButtonOutline, BorderBox} from '@primer/components' import {Link} from 'gatsby' import utilitiesImage from '../src/utilities-image.svg' -import objectsImage from '../src/objects-image.svg' import componentsImage from '../src/components-image.svg' import typographyImage from '../src/typography-image.png' import colorImage from '../src/color-image.svg' @@ -22,14 +21,13 @@ Our goal is to create a system that enables us to build consistent user experien Styles can be mixed and matched to achieve many different layouts, independent of their location. These styles fall into three categories: - + {[ { name: 'Utilities', description: 'Single purpose, immutable styles, that do one thing well.', image: utilitiesImage }, - {name: 'Objects', description: 'Scaffolding for common page and content layouts.', image: objectsImage}, {name: 'Components', description: 'Abstracted patterns for frequently used visual styles.', image: componentsImage} ].map(({name, description, image}) => ( diff --git a/docs/content/marketing/index.md b/docs/content/marketing/index.md new file mode 100644 index 00000000..0d3b44dd --- /dev/null +++ b/docs/content/marketing/index.md @@ -0,0 +1,6 @@ +--- +title: Marketing +path: marketing/index +--- + +The marketing components and utilities are meant for marketing pages. Note that on github.com they are not available for product pages. diff --git a/docs/content/objects/index.md b/docs/content/objects/index.md deleted file mode 100644 index 9b647366..00000000 --- a/docs/content/objects/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Objects -path: objects/index ---- - -Objects help us with common layout patterns but aren't concerned with thematic styles. Examples include the table object, the grid, and the media object. Objects essentially provide some scaffolding for layouts and should be able to be used with other objects, components, and utilities. diff --git a/docs/content/objects/table-object.md b/docs/content/objects/table-object.md deleted file mode 100644 index a3913dcf..00000000 --- a/docs/content/objects/table-object.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Table object -path: objects/table-object -status: Deprecated -source: 'https://github.com/primer/css/tree/main/src/table-object' -bundle: table-object ---- - -The table object is a module for creating dynamically resizable elements that always sit on the same horizontal line (e.g., they never break to a new line). Using table styles in our CSS means it's cross browser friendly back to at least IE9. - -Additional `margin` or `padding` may be required to properly space content. - -```html live title="Table object" -
-
- -
-
- -
-
-``` diff --git a/docs/content/principles/index.md b/docs/content/principles/index.md index 9fc03f32..9a9baf6f 100644 --- a/docs/content/principles/index.md +++ b/docs/content/principles/index.md @@ -5,7 +5,7 @@ path: principles/index The CSS styleguide enables us to create a consistent user experience across GitHub, manage CSS bloat, and make our CSS easier to maintain. These principles should serve as guidelines for how we write and use CSS. - + ## Styleguide driven design and development @@ -14,7 +14,7 @@ Every time new CSS is added it increases our CSS bloat, CSS maintenance, and can _If new styles are needed:_ * Use global variables where appropriate, such as spacing, typography, and color variables. -* Write styles in a way that can be folded back into the global style guide should it become a common pattern, i.e. following our principles for naming conventions, components, objects, and utilities as listed below. +* Write styles in a way that can be folded back into the global style guide should it become a common pattern, i.e. following our principles for naming conventions, components, and utilities as listed below. ## Obvious and transparent @@ -74,26 +74,9 @@ Components make it easier to mark up a set of elements that are commonly grouped .flash-error {...} ``` -## Objects - -Objects help us with common layout patterns but aren't concerned with thematic styles. Examples include the table object, the grid, and the media object. Objects essentially provide some scaffolding for layouts and should be able to be used with other objects, components, and utilities. - -Example: - -```html -
-
- -
-
- -
-
-``` - ## BEM-style naming and structure -Components and objects should follow the [Block Element Modifier](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) (BEM) model in terms of structure. We've chosen to use a modified form of BEM syntax using [uppercase](https://en.wikipedia.org/wiki/Uppercase) for the block name, hyphens and lowercase for elements, and double-hyphens and lowercase for modifiers. When a block class requires two words use [Pascal case](https://en.wikipedia.org/wiki/PascalCase), for example `ProgressBar`. When an element or modifier class requires two words use [camel case](https://en.wikipedia.org/wiki/camelCase), for example `[Component]-closeButton` or `[Component]--extraLarge`. +Components should follow the [Block Element Modifier](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) (BEM) model in terms of structure. We've chosen to use a modified form of BEM syntax using [uppercase](https://en.wikipedia.org/wiki/Uppercase) for the block name, hyphens and lowercase for elements, and double-hyphens and lowercase for modifiers. When a block class requires two words use [Pascal case](https://en.wikipedia.org/wiki/PascalCase), for example `ProgressBar`. When an element or modifier class requires two words use [camel case](https://en.wikipedia.org/wiki/camelCase), for example `[Component]-closeButton` or `[Component]--extraLarge`. * **Block**: A block includes all of the base styles you want shared across every variation of a component. Minimal thematic styling should be applied to blocks, particularly when variations of a component include visual variations. Apply additional styles with modifers rather than overriding base styles. * **Element**: An element is part of a component. Elements should work together with other elements and can have modifiers. Element styles should not override block styles - this often results in applying more styles directly to elements rather than having styles flow down from the parent level. @@ -116,7 +99,7 @@ Components and objects should follow the [Block Element Modifier](http://csswiza ``` ## Property order -For base styles, components, and objects, follow the following property order. +For base styles and components follow the following property order. ```scss .element { diff --git a/docs/content/support/breakpoints.md b/docs/content/support/breakpoints.md index e6511fde..8e38c5da 100644 --- a/docs/content/support/breakpoints.md +++ b/docs/content/support/breakpoints.md @@ -17,7 +17,7 @@ We use abbreviations for each breakpoint to keep the class names concise. This a | Large | lg | `1012px` | | Extra-large | xl | `1280px` | -Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/objects/grid#responsive-grids) system, and many more. +Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/utilities/grid#responsive-grids) system, and many more. ## Breakpoint and up... πŸ›« diff --git a/docs/content/tools/atom-packages.md b/docs/content/tools/atom-packages.md deleted file mode 100644 index 851ef3f9..00000000 --- a/docs/content/tools/atom-packages.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Atom packages -path: tools/atom-packages ---- - -[Atom editor](https://atom.io/) is a _"A hackable text editor for the 21st Century"_ built by GitHub. If you use it as your editor of choice, the design systems team has a list of packages that we find useful for CSS development. - -We keep a list of suggested packages in our [atom-packages repository](https://github.com/primer/atom-packages). To install all packages, run this command in your terminal. - -```sh -apm install $(curl -L https://raw.githubusercontent.com/primer/atom-packages/master/packages) -``` - -## Autocomplete Primer - -The [Autocomplete Primer package](https://atom.io/packages/autocomplete-primer) is a custom [Primer](https://github.com/primer) package that autocompletes class names for [utilities](/utilities) and Rails helper tags for [Octicons](https://github.com/primer/octicons/tree/master/lib/octicons_helper#readme). - -Install [autocomplete-primer](https://atom.io/packages/autocomplete-primer) using Atom's package manager or enter this into your terminal: - -```sh -apm install autocomplete-primer -``` - -## Color picker - -[Color picker](https://atom.io/packages/color-picker) adds a color picking overlay with sliders and color wheels. - -Install [color-picker](https://atom.io/packages/color-picker) using Atom's package manager or enter this into your terminal: - -```sh -apm install color-picker -``` - -## Pigments - -[Pigments](https://atom.io/packages/pigments) adds corresponding backgrounds to CSS color values in the editor for higher visibility. It also scans the source files for color variables and displays the true value. - -Install [pigments](https://atom.io/packages/pigments) using Atom's package manager or enter this into your terminal: - -```sh -apm install pigments -``` - -## Stylelint linter - -We use [Stylelint](https://stylelint.io/), an extension to the [Atom linter package](https://atom.io/packages/linter), for [linting our SCSS](/tools/linting). To prevent linting errors during the build we recommend you install [linter-stylelint](https://atom.io/packages/linter-stylelint), which will alert you of any errors locally while you work. - -Install [linter-stylelint](https://atom.io/packages/linter-stylelint) using Atom's package manager or enter this into your terminal: - -```sh -apm install linter linter-stylelint -``` diff --git a/docs/content/tools/docset.md b/docs/content/tools/docset.md deleted file mode 100644 index 444c5d92..00000000 --- a/docs/content/tools/docset.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Docset -path: tools/docset ---- - -We use and ❀️ [Kapeli's Dash app][dash] for browsing API documentation. Dash comes with 150+ offline documentation sets, but doesn't have our style guide. - -So we've generated a [GitHub Style Guide docset][dash-feed] that gives you access to this site offline. - -## Installation - -1. First you'll need to make sure you have [Dash app][dash] installed. -2. Once installed, open the app, and click this [install docset link][dash-feed]. -3. After the docset has been added to your list, click "download". -![](https://user-images.githubusercontent.com/54012/32087284-a87ed8f4-ba8f-11e7-9d84-c61913336491.png) - -[dash]: https://kapeli.com/dash -[dash-feed]: dash-feed://https%3A%2F%2Fstyleguide.github.com%2Ffeeds%2FGitHub%20Style%20Guide.xml diff --git a/docs/content/tools/linting.md b/docs/content/tools/linting.md index 2228b6ba..f5d79531 100644 --- a/docs/content/tools/linting.md +++ b/docs/content/tools/linting.md @@ -72,13 +72,7 @@ While linters shouldn't be disabled without consideration, essentially they act ### Plugins -Our linter runs on every commit, but finding you have a lint error after a push can be frustrating and waste time. To avoid this, a [collection of editor plugins](http://stylelint.io/user-guide/complementary-tools/) are available to help you lint while you code.. - -The Design Systems team recommends using [Atom](https://atom.io/) with the [linter-stylelint](https://github.com/AtomLinter/linter-stylelint) package installed. - -![image](https://cloud.githubusercontent.com/assets/54012/21456489/6a10b370-c8f6-11e6-9199-bb3709e79794.png) - -We also have a [list of Atom packages](/tools/atom-packages) that we find useful for development. +Our linter runs on every commit, but finding you have a lint error after a push can be frustrating and waste time. To avoid this, a [collection of editor plugins](https://stylelint.io/user-guide/integrations/editor) are available to help you lint while you code. ## HTML diff --git a/docs/content/tools/local-primer.md b/docs/content/tools/local-primer.md deleted file mode 100644 index e495293e..00000000 --- a/docs/content/tools/local-primer.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Local development -internal: true -path: tools/local-primer ---- - -When you are working with the `github/github` codebase, you can link Primer CSS modules with your local development environment using the Primerize script. This will allow you to make changes to Primer CSS and see them reflected on `github.localhost` without the overhead of pulling in alpha releases of a package. - -## Prerequisites - -1. Working with `github/github` on the latest codebase. -2. Cloned down latest version of [primer/primer](https://github.com/primer/primer). -3. The `github/github` folder and the `primer/primer` folder must share the same parent folder. - -**Example:** -``` -~/codefolder/ -β”œβ”€β”€ github -└── primer -``` - -## Linking to your local Primer CSS repository - -In your terminal start the server with the environment variable `LOCAL_PRIMER=1`. For example. - -``` -> LOCAL_PRIMER=1 script/server -``` - -When the variable is present, the script will check for linked local Primer CSS packages. If it's not linked, then it will proceed to link the Primer CSS packages in `../primer` to your GitHub application. When the server starts with successfully linked packages, you will see a clear message. - -**Example output:** - -``` -❯ LOCAL_PRIMER=1 script/server --------------------------------------------------------------------------------- - Development Primer is linked to the local Primer repository found here - /Users/usera/github/primer --------------------------------------------------------------------------------- -14:09:14 web.1 | started with pid 36981 -14:09:14 assets.1 | started with pid 36982 -14:09:14 longpoll.1 | started with pid 36984 -14:09:14 git-daemon.1 | started with pid 36986 -14:09:14 gitauth.1 | started with pid 36988 -14:09:14 codeload.1 | started with pid 36991 -14:09:14 babeld.1 | started with pid 36996 -``` - -## Resetting github/github development assets - -To turn off Primerize, rerun `script/server` without the `LOCAL_PRIMER` flag. The script checks if you are still linked and restores everything to normal. - -**Example output:** - -``` -❯ script/server --------------------------------------------------------------------------------- - Development Primer is linked to the local Primer repository found here - /Users/usera/github/primer --------------------------------------------------------------------------------- -Turning off linked primer -extracting primer-alerts@1.5.5.tgz -extracting primer-avatars@1.5.2.tgz -extracting primer-base@1.7.0.tgz -extracting primer-blankslate@1.4.5.tgz -extracting primer-box@2.5.5.tgz -extracting primer-branch-name@1.0.3.tgz -extracting primer-breadcrumb@1.5.1.tgz -extracting primer-buttons@2.5.3.tgz -extracting primer-core@6.8.0.tgz -extracting primer-forms@2.1.0.tgz -extracting primer-labels@1.5.5.tgz -extracting primer-layout@1.4.5.tgz -extracting primer-markdown@3.7.5.tgz -extracting primer-marketing-buttons@1.0.4.tgz -extracting primer-marketing-support@1.5.0.tgz -extracting primer-marketing-type@1.4.5.tgz -extracting primer-marketing-utilities@1.6.1.tgz -extracting primer-marketing@6.2.0.tgz -extracting primer-navigation@1.5.3.tgz -extracting primer-page-headers@1.4.5.tgz -extracting primer-page-sections@1.4.5.tgz -extracting primer-popover@0.0.6.tgz -extracting primer-product@5.6.2.tgz -extracting primer-subhead@1.0.3.tgz -extracting primer-support@4.5.2.tgz -extracting primer-table-object@1.4.5.tgz -extracting primer-tables@1.4.5.tgz -extracting primer-tooltips@1.5.3.tgz -extracting primer-truncate@1.4.5.tgz -extracting primer-utilities@4.8.5.tgz -extracting primer@10.4.0.tgz -regenerating node binstubs -14:13:17 web.1 | started with pid 38585 -14:13:17 assets.1 | started with pid 38586 -``` diff --git a/docs/content/utilities/flexbox.md b/docs/content/utilities/flexbox.md index 124e2b75..582acbfa 100644 --- a/docs/content/utilities/flexbox.md +++ b/docs/content/utilities/flexbox.md @@ -707,7 +707,7 @@ Resize window to see the effect. ## Responsive flex utilities -All flexbox utilities can be adjusted per [breakpoint](/objects/grid#breakpoints) using the following formulas: +All flexbox utilities can be adjusted per [breakpoint](/utilities/grid#breakpoints) using the following formulas: - `d-[breakpoint]-[property]` for `display` - `flex-[breakpoint]-[property]-[behavior]` for various flex properties diff --git a/docs/content/objects/grid.md b/docs/content/utilities/grid.md similarity index 99% rename from docs/content/objects/grid.md rename to docs/content/utilities/grid.md index 887c5867..40d5a647 100644 --- a/docs/content/objects/grid.md +++ b/docs/content/utilities/grid.md @@ -1,6 +1,6 @@ --- title: Grid -path: objects/grid +path: utilities/grid status: Stable status_issue: 'https://github.com/github/design-systems/issues/88' source: 'https://github.com/primer/css/tree/main/src/layout/grid.scss' @@ -9,6 +9,25 @@ bundle: layout The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts. The grid system works with a variety of layout utilities to achieve different results. +## Flexbox grids + +You can use [flex utilities](/utilities/flexbox) on the container and columns to create a flexbox grid. + +This can be useful for keeping columns the same height, justifying content and vertically aligning items. The flexbox grid is also great for working with responsive layouts. + +```html live title="Flexbox grid" +
+
+ github +
+
+

GitHub

+

How people build software.

+ https://github.com/about +
+
+``` + ## Float based grid Use `.clearfix` on the container and float utilities with columns for a floated grid layout. @@ -27,7 +46,7 @@ Use `.clearfix` on the container and float utilities with columns for a floated
``` -### Reversed grid +### Reversed float grid To reverse the order of columns, use `float-right` to float columns to the right. @@ -284,25 +303,6 @@ Note that table cells will fill the width of their container even when the total ``` -## Flexbox grids - -You can use [flex utilities](/utilities/flexbox) on the container and columns to create a flexbox grid. - -This can be useful for keeping columns the same height, justifying content and vertically aligning items. The flexbox grid is also great for working with responsive layouts. - -```html live title="Flexbox grid" -
-
- github -
-
-

GitHub

-

How people build software.

- https://github.com/about -
-
-``` - ## Responsive grids All the column width classes can be set per breakpoint to create responsive grid layouts. Each responsive style is applied to the specified breakpoint and up. diff --git a/docs/content/utilities/layout.md b/docs/content/utilities/layout.md index f713a5f5..d941802f 100644 --- a/docs/content/utilities/layout.md +++ b/docs/content/utilities/layout.md @@ -54,7 +54,7 @@ element.classList.toggle('d-inline', visible) ### `display:table` wrapping issues -There are known issues with using `display:table` and wrapping long strings, particularly in Firefox. You may need to use `table-fixed` on elements with `d-table` and apply column widths to table cells, which you can do with our [column width styles](/objects/grid#column-widths). +There are known issues with using `display:table` and wrapping long strings, particularly in Firefox. You may need to use `table-fixed` on elements with `d-table` and apply column widths to table cells, which you can do with our [column width styles](/utilities/grid#column-widths). ```html live
@@ -68,7 +68,7 @@ There are known issues with using `display:table` and wrapping long strings, par ``` ### Responsive display -A selection of display utilities are able to be applied or changed per [breakpoint](/objects/grid#breakpoints). `.d-block`, `.d-none`, `.d-inline`, and `.d-inline-block` are available as responsive utilities using the following formula: `d-[breakpoint]-[property]`. For example: `d-md-inline-block`. Each responsive display utility is applied to the specified breakpoint and up. +A selection of display utilities are able to be applied or changed per [breakpoint](/utilities/grid#breakpoints). `.d-block`, `.d-none`, `.d-inline`, and `.d-inline-block` are available as responsive utilities using the following formula: `d-[breakpoint]-[property]`. For example: `d-md-inline-block`. Each responsive display utility is applied to the specified breakpoint and up. In the following example, the `ul` element switches from `display: block` on mobile to `display: inline-block` at the `md` breakpoint, while the list items remain inline. @@ -118,10 +118,12 @@ Overflow utilities can also target x- and y-axes independently via: * `.overflow-y-scroll` * `.overflow-y-visible` -Overflow utilities can be applied or changed per [breakpoint](/objects/grid#breakpoints). Each **responsive** overflow utility is applied to the specified breakpoint and up, using the following formula: `overflow-[breakpoint]-[axis]-[property]`. For example: `overflow-x-scroll` or `overflow-md-x-visible`. +Overflow utilities can be applied or changed per [breakpoint](/utilities/grid#breakpoints). Each **responsive** overflow utility is applied to the specified breakpoint and up, using the following formula: `overflow-[breakpoint]-[axis]-[property]`. For example: `overflow-x-scroll` or `overflow-md-x-visible`. ## Floats -Use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear. + +Using floats are discouraged since [flexbox](/utilities/flexbox) offers more features and doesn't need to be cleared. If you still need it, you can use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear. + ```html live
@@ -133,7 +135,7 @@ Use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear.
``` ### Responsive floats -Float utilities can be applied or changed per [breakpoint](/objects/grid#breakpoints). This can be useful for responsive layouts when you want an element to be full width on mobile but floated at a larger breakpoint. +Float utilities can be applied or changed per [breakpoint](/utilities/grid#breakpoints). This can be useful for responsive layouts when you want an element to be full width on mobile but floated at a larger breakpoint. Each responsive float utility is applied to the specified breakpoint and up, using the following formula: `float-[breakpoint]-[property]`. For example: `float-md-left`. Remember to use `.clearfix` to clear. diff --git a/docs/content/utilities/margin.md b/docs/content/utilities/margin.md index d6b1b53b..1da10b69 100644 --- a/docs/content/utilities/margin.md +++ b/docs/content/utilities/margin.md @@ -116,7 +116,7 @@ Reset margins built into typography elements or other components with `m-0`, `mt ## Responsive margins -All margin utilities can be adjusted per [breakpoint](/objects/grid#breakpoints) using the following formula: `m[direction]-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up. +All margin utilities can be adjusted per [breakpoint](/utilities/grid#breakpoints) using the following formula: `m[direction]-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up. ```html live
diff --git a/docs/content/utilities/padding.md b/docs/content/utilities/padding.md index 91438e62..d2fe9d63 100644 --- a/docs/content/utilities/padding.md +++ b/docs/content/utilities/padding.md @@ -37,7 +37,7 @@ Since padding utilities have many variations and will be used in many places, we | 11 | 112px | | 12 | 128px | -_**Note:** The blue in the examples below represents the element, and the green represents the padding._ +_**Note:** The gray in the examples below represents the element, and the yellow represents the padding._ ## Uniform padding @@ -92,7 +92,7 @@ All padding utilities can be adjusted per [breakpoint](/support/breakpoints) usi ## Responsive container padding -`.p-responsive` is a padding class that adds padding on the left and right sides of an element. It is intended to be used with [container styles](/objects/grid#containers). +`.p-responsive` is a padding class that adds padding on the left and right sides of an element. It is intended to be used with [container styles](/utilities/grid#containers). - On **0 to sm** screens, it gives the element padding of `$spacer-3` - On **sm to lg** screens it gives the element padding of `$spacer-6` diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml index 72a76979..685753d2 100644 --- a/docs/src/@primer/gatsby-theme-doctocat/nav.yml +++ b/docs/src/@primer/gatsby-theme-doctocat/nav.yml @@ -31,27 +31,16 @@ url: /utilities/details - title: Flexbox url: /utilities/flexbox + - title: Grid + url: /utilities/grid - title: Layout url: /utilities/layout - - title: Marketing layout - url: /utilities/marketing-layout - title: Margin url: /utilities/margin - - title: Marketing filters - url: /utilities/marketing-filters - title: Padding url: /utilities/padding - title: Typography url: /utilities/typography - - title: Marketing typography - url: /utilities/marketing-type -- title: Objects - url: /objects - children: - - title: Grid - url: /objects/grid - - title: Table object - url: /objects/table-object - title: Components url: /components children: @@ -91,10 +80,6 @@ url: /components/loaders - title: Markdown url: /components/markdown - - title: Marketing buttons - url: /components/marketing-buttons - - title: Marketing links - url: /components/marketing-links - title: Navigation url: /components/navigation - title: Pagination @@ -115,19 +100,26 @@ url: /components/tooltips - title: Truncate url: /components/truncate +- title: Marketing + url: /marketing + children: + - title: Buttons + url: /components/marketing-buttons + - title: Filters + url: /utilities/marketing-filters + - title: Layout + url: /utilities/marketing-layout + - title: Links + url: /components/marketing-links + - title: Typography + url: /utilities/marketing-type - title: Tools url: /tools children: - - title: Atom packages - url: /tools/atom-packages - title: Deprecation data url: /tools/deprecations - - title: Docset - url: /tools/docset - title: Linting url: /tools/linting - - title: Local development - url: /tools/local-primer - title: Prototyping url: /tools/prototyping - title: Testing resources diff --git a/docs/src/stories/components/Layout/LayoutBeta.stories.jsx b/docs/src/stories/components/Layout/LayoutBeta.stories.jsx index 75a8d681..986f08c4 100644 --- a/docs/src/stories/components/Layout/LayoutBeta.stories.jsx +++ b/docs/src/stories/components/Layout/LayoutBeta.stories.jsx @@ -22,7 +22,7 @@ export default { labels: ['fluid', 'md', 'lg', 'xl'] }, description: - 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/objects/grid#containers) for reference.', + 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/utilities/grid#containers) for reference.', table: { category: 'Structure' } diff --git a/docs/src/stories/components/Layout/PageLayout.stories.jsx b/docs/src/stories/components/Layout/PageLayout.stories.jsx index 2790ec51..30bb5b2d 100644 --- a/docs/src/stories/components/Layout/PageLayout.stories.jsx +++ b/docs/src/stories/components/Layout/PageLayout.stories.jsx @@ -23,7 +23,7 @@ export default { type: 'inline-radio', labels: ['fluid', 'md', 'lg', 'xl'] }, - description: 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/objects/grid#containers) for reference.', + description: 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/utilities/grid#containers) for reference.', table: { category: 'Structure' } diff --git a/src/table-object/README.md b/src/table-object/README.md deleted file mode 100644 index c637286c..00000000 --- a/src/table-object/README.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -bundle: "table-object" -generated: true ---- - -# Primer CSS:Β `table-object` bundle - -## Usage - -Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with: - -```scss -@import "@primer/css/table-object/index.scss"; -``` - -## Build - -The `@primer/css` npm package includes a standalone CSS build of this module in `dist/table-object.css`. - -## License - -[MIT](https://github.com/primer/css/blob/main/LICENSE) © [GitHub](https://github.com/) - - -[scss]: https://sass-lang.com/documentation/syntax#scss diff --git a/src/table-object/table-object.scss b/src/table-object/table-object.scss index 353c7328..04bb304f 100644 --- a/src/table-object/table-object.scss +++ b/src/table-object/table-object.scss @@ -1,3 +1,6 @@ +// Deprecated +// TODO: Replace TableObject with flexbox or a new Table component + // TableObject is a module for creating dynamically resizable elements that // always sit on the same horizontal line (e.g., they never wrap). Using // tables means it's cross browser friendly. diff --git a/vercel.json b/vercel.json index 13a2ce31..5a30a159 100644 --- a/vercel.json +++ b/vercel.json @@ -18,7 +18,12 @@ { "src": "/css/objects/layout/?", "status": 301, - "headers": {"Location": "/css/objects/grid"} + "headers": {"Location": "/css/utilities/grid"} + }, + { + "src": "/css/objects/grid/?", + "status": 301, + "headers": {"Location": "/css/utilities/grid"} }, { "src": "/css(/.*)?",