Add styling docs

ariakit · Apr 12, 2023 · 73156e9 · 73156e9 · vercel · Apr 12, 2023
1 parent a1ac300
commit 73156e9
Show file tree

Hide file tree

Showing 6 changed files with 183 additions and 24 deletions.
diff --git a/.gitpod.yml b/.gitpod.yml
@@ -3,12 +3,6 @@ tasks:
   - name: Development
     init: npm install && gp sync-done install
     command: npm run dev
-    openMode: split-left
-
-  - name: Test
-    init: gp sync-await install
-    command: npm run test
-    openMode: split-right
 
 ports:
   - port: 3000

diff --git a/guide/1-getting-started.md → guide/100-getting-started.md b/guide/1-getting-started.md → guide/100-getting-started.md
@@ -20,24 +20,12 @@ npm i @ariakit/react
 
 ## Usage
 
-<div class="note">
-
-[Play with Ariakit on CodeSandbox](https://codesandbox.io/s/m4n32vjkoj)
-
-</div>
-
 Ariakit exports a set of [unstyled](/guide/styling) React components and hooks that you can use to build accessible web apps. For example, you can use the [Button](/components/button) component to create a button:
 
 <a href="../examples/button/index.tsx" data-playground type="compact">Example</a>
 
 ## CDN
 
-<div class="note">
-
-[Play with Ariakit on JSBin](https://jsbin.com/funovaqiza/edit?html,output)
-
-</div>
-
 You can also use Ariakit directly in the browser via a CDN. This method is only for development purposes and is not recommended for production.
 
 ```html

diff --git a/guide/200-styling.md b/guide/200-styling.md
@@ -0,0 +1,173 @@
+# Styling
+
+<p data-description>
+  Ariakit provides unstyled components by default. You're free to style them using your favorite styling method.
+</p>
+
+## Applying styles
+
+Ariakit components accept all native props, including `className`, `style`, and `ref`. You can use them to apply your styles just like you would with any other React element.
+
+## CSS selectors
+
+**Important: Do not use any selectors that are not listed below.**
+
+Ariakit renders elements with HTML attributes, such as `role`, that should not be used as CSS selectors as they're not part of the public API and may change in future minor and patch releases.
+
+To safely use CSS selectors, utilize the `className` prop or provide your own `data-*` attributes to the component. Refer to the list below for all the selectors that are safe to use.
+
+### `[aria-disabled]`
+
+Not all HTML elements accept the `disabled` attribute. That's why the [Focusable](/components/focusable) component and all components that use it underneath will apply the `aria-disabled` attribute to the rendered element when the `disabled` prop is set to `true`.
+
+```css
+.button[aria-disabled="true"] {
+  opacity: 0.5;
+}
+```
+
+### `[aria-expanded]`
+
+The `aria-expanded` attribute is applied to the [Disclosure](/components/disclosure) component and all components that use it underneath, such as [PopoverDisclosure](/components/popover), [MenuButton](/components/menu), and [Select](/components/select), when the content element is shown.
+
+```css
+.button[aria-expanded="true"] {
+  background-color: #eee;
+}
+```
+
+### `[data-active]`
+
+The `data-active` attribute is applied to clickable components, such as [Command](/components/command) and [Button](/components/button), to simulate the `:active` pseudo-class when the components are not rendered as native `button` elements.
+
+It's important to note that, to avoid doing unnecessary work, the `data-active` attribute is not applied to components that are rendered as `button` elements. Therefore, you should use both the `:active` and `[data-active]` selectors to keep your styles consistent.
+
+```css
+.button:active,
+.button[data-active] {
+  background-color: #eee;
+}
+```
+
+### `[data-active-item]`
+
+The `data-active-item` attribute is applied to composite widget items when they receive focus or are hovered (when the [`focusOnHover`](/apis/composite-hover#focusonhover) prop is set to `true`). Besides the [Composite](/components/composite) component itself, composite widgets include [Combobox](/components/combobox), [Menu](/components/menu), [Radio](/components/radio), [Select](/components/select), [Tab](/components/tab), and [Toolbar](/components/toolbar).
+
+```css
+.item[data-active-item] {
+  background-color: #eee;
+}
+```
+
+### `[data-autofill]`
+
+The `data-autofill` attribute is applied to the [Select](/component/select) component when it's used within a form and the value has been autofilled by the browser.
+
+```css
+.select[data-autofill] {
+  background-color: rgb(219 237 255);
+}
+```
+
+### `[data-enter]`
+
+When [Disclosure](/components/disclosure) components have the `animated` state set to `true`, they will apply the `data-enter` attribute to the rendered element when its being shown. This happens with a short delay to allow the browser to paint the element before the animation starts.
+
+```css
+.dialog {
+  transform: scale(0.9);
+  transition: transform 200ms;
+}
+
+.dialog[data-enter] {
+  transform: scale(1);
+}
+```
+
+### `[data-leave]`
+
+Similar to [`data-enter`](#data-enter), when [Disclosure](/components/disclosure) components have the `animated` state set to `true`, they will apply the `data-leave` attribute to the rendered element when its being hidden.
+
+Usually, you just need `data-enter`. The animation will be reversed when the element is hidden. However, if you want to style the exit animation in a different way, you can use `data-leave` to do so.
+
+```css
+.dialog {
+  transform: scale(1);
+  transition: transform 200ms;
+}
+
+.dialog[data-leave] {
+  transform: scale(0.9);
+}
+```
+
+### `[data-focus-visible]`
+
+The `data-focus-visible` attribute is applied to the [Focusable](/components/focusable) component and all components that use it underneath when there's a keyboard interaction on a focusable element.
+
+It works the same way as the [`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible) pseudo-class. However, unlike `:focus-visible`, the `data-focus-visible` attribute is also applied to composite widget items, such as [ComboboxItem](/components/combobox), when they receive [`virtualFocus`](/apis/composite-store#virtualfocus).
+
+If you're styling Ariakit components, it's recommended to use the `[data-focus-visible]` selector to keep your styles consistent.
+
+```css
+.button[data-focus-visible] {
+  outline: 2px solid #007acc;
+}
+```
+
+## CSS variables
+
+Some components, such as [Popover](/components/popover), [Menu](/components/menu), [Hovercard](/components/hovercard), [SelectPopover](/components/select), [ComboboxPopover](/components/comboboxPopover), among others, expose CSS variables that you can use to customize their appearance.
+
+### `--popover-anchor-width`
+
+The `--popover-anchor-width` variable exposes the width value of the anchor element. It's useful when you want to make the popover element have the same width as the anchor element.
+
+```css
+.combobox-popover {
+  /* The combobox popover will have the same width as the combobox input */
+  width: var(--popover-anchor-width);
+}
+```
+
+### `--popover-available-height`
+
+The `--popover-available-height` variable exposes the available vertical space in the viewport. You can use this to make the popover element have a maximum height that fits the available space.
+
+```css
+.popover {
+  max-height: var(--popover-available-height);
+}
+```
+
+### `--popover-available-width`
+
+The `--popover-available-width` variable exposes the available horizontal space in the viewport. You can use this to make the popover element have a maximum width that fits the available space.
+
+```css
+.popover {
+  max-width: var(--popover-available-width);
+}
+```
+
+### `--popover-overflow-padding`
+
+The `--popover-overflow-padding` variable exposes the amount of padding that should be added between the popover element and the viewport edges. You can use this in combination with `100%` or `100vw` values to make the popover element fill the entire viewport width, while still keeping the padding.
+
+```css
+.popover {
+  width: calc(100vw - var(--popover-overflow-padding) * 2);
+}
+```
+
+### `--scrollbar-width`
+
+The [Dialog](/components/dialog) component will define a `--scrollbar-width` CSS variable on the `html` element when a modal dialog is open. Since the scrollbar is hidden when a modal dialog is open, this variable can be used to adjust the right padding of your `position: fixed` elements.
+
+```css
+.header {
+  position: fixed;
+  padding-inline: 16px;
+  padding-inline-end: calc(16px + var(--scrollbar-width, 0));
+}
+```
diff --git a/tailwind.config.cjs b/tailwind.config.cjs
@@ -8,9 +8,9 @@ const white = "hsl(204 20% 100%)";
 /** @type {import('tailwindcss/tailwind-config').TailwindConfig} */
 module.exports = {
   content: [
-    "app/**/*.{js,jsx,ts,tsx}",
-    "components/**/*.{js,jsx,ts,tsx}",
-    "icons/**/*.{js,jsx,ts,tsx}",
+    path.join(__dirname, "website/app/**/*.{ts,tsx}"),
+    path.join(__dirname, "website/components/**/*.{ts,tsx}"),
+    path.join(__dirname, "website/icons/**/*.{ts,tsx}"),
   ],
   darkMode: "class",
   theme: {

diff --git a/website/app/(main)/[category]/[page]/page.tsx b/website/app/(main)/[category]/[page]/page.tsx
@@ -21,6 +21,10 @@ import { tw } from "utils/tw.js";
 import { PageExample } from "./page-example.js";
 import { TableOfContents } from "./table-of-contents.js";
 
+// Workaround for getting fast refresh to work when markdown files are updated.
+// See https://twitter.com/diegohaz/status/1646192312630779905
+import "build-pages/contents.js";
+
 const { pages } = pagesConfig;
 
 const stickyHeading = tw`

diff --git a/website/components/code-block.tsx b/website/components/code-block.tsx
@@ -90,10 +90,10 @@ export async function CodeBlock({
         )}
         <code
           className={cx(
-            type === "static" && "sm:mx-8",
+            type === "static" && "sm:!mx-8",
             type === "static" && lineNumbers && "!ml-0",
-            type === "editor" && lineNumbers && "sm:ml-0",
-            "mx-4 ml-[26px]"
+            type === "editor" && lineNumbers && "sm:!ml-0",
+            "mx-4 sm:ml-[26px]"
           )}
         >
           {tokens.map((line, i) => (