@@ -159,7 +159,7 @@ const createLoginLayout = () => {
}
}
-
+
@@ -195,22 +195,24 @@ const createLoginLayout = () => {
const createUtilityLayout = () => {
return `
-
+
-
+
-
Timeline with Icons
+Timeline with Icons
-
- nature
-
- Buried by
- Squirrel
-
+
@@ -243,16 +245,20 @@ const createUtilityLayout = () => {
-
+
+
Mar 31
+ 
+
+
+
+ Squirrel
+ Animal
+
Timeline with Icons
-
-Utility classes are simple CSS classes scoped to a simple style property like flex or gap.
-They can be added together to style a portion of your HTML from scratch.
-This is especially useful for quickly scaffolding out page layouts.
+Utility classes are CSS classes scoped to a simple style property like flex or gap or a collection of related properties.
+They can be combined together to quickly scaffold out page layouts or a portion of your HTML.
Optics provides limited but high value utility classes. Utilities can often and easily lead to poorly written CSS,
inconsistent styling, or unresponsive layouts. However, there are cases where utilities can provide great value.
@@ -69,13 +68,13 @@ This will allow for more complex layout to be managed within a named CSS class a
- If your layout needs to handle breakpoints or special responsive rules, utilities are going to get in the way of making this easy. You probably want to name the concept.
- If a particular collection of utilities is getting used together often, it may point to a UI pattern in your design that should be named.
-### Higher Order Utilities vs Components
+### Advanced Utilities vs Components
While flex utilities are great for moving quickly or for simple layouts, they can easily become
cumbersome to manage and tend to turn into "Flex Spaghetti". In some of these cases, reaching
for named components may make sense. However, there are times when a full component is more
restrictive than you need and hurts productivity. Sometimes you need just a bit more structure
-to your layout, but not a component. [Stack](?path=/docs/utilities-stack--docs), [Cluster](?path=/docs/utilities-cluster--docs), and [Split](?path=/docs/utilities-split--docs)
+to your layout, but not a component. [Stack](?path=/docs/utilities-advanced-stack--docs), [Cluster](?path=/docs/utilities-advanced-cluster--docs), [Split](?path=/docs/utilities-advanced-split--docs), [Flank](?path=/docs/utilities-advanced-flank--docs), and [Grid](?path=/docs/utilities-advanced-grid--docs)
provide a simple way to create readable, flexible layouts without the overhead of a full component.
## A word of warning
- nature
-
- Buried by
- squirrel
-
+
@@ -286,6 +292,73 @@ const createUtilityLayout = () => {
`
}
+const createCardGridLayout = () => {
+ return `
+
+
Mar 31
+
+
+
+
+
+ Squirrel
+ Animal
+
+
+
+
+
+
+
+`
+}
+
export const createLayout = ({ style = 'basic', rightSidebar = false }) => {
if (style === 'basic') {
return createBasicLayout()
@@ -315,5 +388,9 @@ export const createLayout = ({ style = 'basic', rightSidebar = false }) => {
return createUtilityLayout()
}
+ if (style === 'card-grid') {
+ return createCardGridLayout()
+ }
+
return ``
}
diff --git a/src/stories/Recipes/Layout/Layout.mdx b/src/stories/Recipes/Layout/Layout.mdx
index d1be640c..66604309 100644
--- a/src/stories/Recipes/Layout/Layout.mdx
+++ b/src/stories/Recipes/Layout/Layout.mdx
@@ -259,6 +259,14 @@ A layout for a login page could look like the following:
### Utility
-A layout explaining how the stack, split, and cluster utilities can be used to make flex layouts more readable.
+A layout explaining how the stack, split, cluster, and flank utilities can be used to make flex layouts more readable.
+
+### Card Grid
+
+A responsive card grid built with the `op-grid` and `op-frame` utilities. The `op-frame` utility keeps each card's
+media at a consistent aspect ratio regardless of the source image dimensions, and it isn't limited to media — the
+"Coming soon" card frames a text placeholder to hold the same shape.
+
+
diff --git a/src/stories/Recipes/Layout/Layout.stories.js b/src/stories/Recipes/Layout/Layout.stories.js
index f5c8f100..1d62c93e 100644
--- a/src/stories/Recipes/Layout/Layout.stories.js
+++ b/src/stories/Recipes/Layout/Layout.stories.js
@@ -8,7 +8,7 @@ export default {
argTypes: {
style: {
control: { type: 'select' },
- options: ['basic', 'sidebar', 'navbar', 'spinner', 'sidepanel', 'login', 'utility'],
+ options: ['basic', 'sidebar', 'navbar', 'spinner', 'sidepanel', 'login', 'utility', 'card-grid'],
},
rightSidebar: {
control: { type: 'boolean' },
@@ -68,3 +68,9 @@ export const Utility = {
style: 'utility',
},
}
+
+export const CardGrid = {
+ args: {
+ style: 'card-grid',
+ },
+}
diff --git a/src/stories/Utilities/Cluster/Cluster.js b/src/stories/Utilities/Advanced/Cluster/Cluster.js
similarity index 86%
rename from src/stories/Utilities/Cluster/Cluster.js
rename to src/stories/Utilities/Advanced/Cluster/Cluster.js
index 5a9e435a..9a5f680f 100644
--- a/src/stories/Utilities/Cluster/Cluster.js
+++ b/src/stories/Utilities/Advanced/Cluster/Cluster.js
@@ -1,4 +1,4 @@
-import { createChildren } from '../../helpers/utils'
+import { createChildren } from '../../../helpers/utils'
export const createCluster = ({ cluster = true, alignItems = '', gap = '' }) => {
const wrapper = document.createElement('div')
diff --git a/src/stories/Utilities/Cluster/Cluster.mdx b/src/stories/Utilities/Advanced/Cluster/Cluster.mdx
similarity index 96%
rename from src/stories/Utilities/Cluster/Cluster.mdx
rename to src/stories/Utilities/Advanced/Cluster/Cluster.mdx
index 0ea45cb6..d0eff28a 100644
--- a/src/stories/Utilities/Cluster/Cluster.mdx
+++ b/src/stories/Utilities/Advanced/Cluster/Cluster.mdx
@@ -1,6 +1,6 @@
import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks'
import * as ClusterStories from './Cluster.stories'
-import { createSourceCodeLink } from '../../helpers/sourceCodeLink.js'
+import { createSourceCodeLink } from '../../../helpers/sourceCodeLink.js'
diff --git a/src/stories/Utilities/Cluster/Cluster.stories.js b/src/stories/Utilities/Advanced/Cluster/Cluster.stories.js
similarity index 90%
rename from src/stories/Utilities/Cluster/Cluster.stories.js
rename to src/stories/Utilities/Advanced/Cluster/Cluster.stories.js
index dbba4f28..035090e3 100644
--- a/src/stories/Utilities/Cluster/Cluster.stories.js
+++ b/src/stories/Utilities/Advanced/Cluster/Cluster.stories.js
@@ -1,7 +1,7 @@
import { createCluster } from './Cluster.js'
export default {
- title: 'Utilities/Cluster',
+ title: 'Utilities/Advanced/Cluster',
render: ({ cluster, ...args }) => {
return createCluster({ cluster, ...args })
},
@@ -13,7 +13,7 @@ export default {
},
gap: {
control: { type: 'select' },
- options: ['xxs', 'xs', 'sm', 'md', 'lg', 'xl'],
+ options: ['none', 'xxs', 'xs', 'sm', 'md', 'lg', 'xl'],
},
},
parameters: {
diff --git a/src/stories/Utilities/Advanced/Flank/Flank.js b/src/stories/Utilities/Advanced/Flank/Flank.js
new file mode 100644
index 00000000..a4a8fb12
--- /dev/null
+++ b/src/stories/Utilities/Advanced/Flank/Flank.js
@@ -0,0 +1,46 @@
+import { createChildren } from '../../../helpers/utils'
+import { createAvatar } from '../../../Components/Avatar/Avatar'
+import { createTextPair } from '../../../Components/TextPair/TextPair'
+
+export const createFlank = ({ flank = true, end = false, gap = '', example = false }) => {
+ if (example) {
+ return createAvatarExample({ flank, end, gap })
+ }
+
+ const wrapper = document.createElement('div')
+
+ wrapper.className = classlist(flank, end, gap)
+
+ createChildren(wrapper, 2)
+
+ return wrapper
+}
+
+const createAvatarExample = ({ flank, end, gap }) => {
+ const avatar = createAvatar({
+ size: 'large',
+ useLink: false,
+ imageSource: 'https://avatars.githubusercontent.com/u/5957102?v=4',
+ }).outerHTML
+ const textPairEl = createTextPair({ titleText: 'Jeremy Walton', subtitleText: 'RoleModel Software' })
+ if (end) textPairEl.classList.add('text-right')
+ const textPair = textPairEl.outerHTML
+
+ // Reverse order of elements if end is true
+ const [first, second] = end ? [textPair, avatar] : [avatar, textPair]
+
+ return `
+
+
+
+
+
+
+
+
+ 
+
+
+
+
+
+ Clint
+ Dog · Male
+
+
+
+
+
+
+
+
+ photo
+
+ Coming soon
+
+
+
+
+ Daisy
+ Dog · Female
+
+
+
+
+
+ 
+
+
+
+
+
+ June
+ Dog · Female
+
+
+
+
+ 
+
+
+
+
+
+ Wallace
+ Dog · Male
+
+
+
+`
+}
+
+const classlist = (flank, end, gap) => {
+ return [flank ? 'op-flank' : '', flank && end ? 'op-flank--end' : '', gap ? `gap-${gap}` : '']
+ .filter(Boolean)
+ .join(' ')
+}
diff --git a/src/stories/Utilities/Advanced/Flank/Flank.mdx b/src/stories/Utilities/Advanced/Flank/Flank.mdx
new file mode 100644
index 00000000..925d82a7
--- /dev/null
+++ b/src/stories/Utilities/Advanced/Flank/Flank.mdx
@@ -0,0 +1,57 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as FlankStories from './Flank.stories'
+import { createSourceCodeLink } from '../../../helpers/sourceCodeLink.js'
+
+
+
+# Flank
+
+
+
+The flank utility provides a simple way to create a horizontal row with an item flanked by another large item. It
+works with all of the gap and other flex utilities.
+
+See [Utility Introduction](?path=/docs/utilities-introduction--docs#higher-order-utilities-vs-components) for more information.
+
+See [Utility Layout](?path=/docs/recipes-layout--docs#utility) for an example of how flanks
+can be used to create more readable flex layouts.
+
+Note: This utility uses the `op` prefix to avoid potential naming conflicts with other CSS frameworks.
+This is a pattern we hope to move towards for all utilities in the future.
+
+## Playground
+
+
+
+ ${first}
+ ${second}
+
+
+
+`
+}
+
+const classlist = (frame, aspect) => {
+ return [frame ? 'op-frame' : '', frame && aspect ? `op-frame--${aspect}` : ''].filter(Boolean).join(' ')
+}
diff --git a/src/stories/Utilities/Advanced/Frame/Frame.mdx b/src/stories/Utilities/Advanced/Frame/Frame.mdx
new file mode 100644
index 00000000..90f09b48
--- /dev/null
+++ b/src/stories/Utilities/Advanced/Frame/Frame.mdx
@@ -0,0 +1,88 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as FrameStories from './Frame.stories.js'
+import { createSourceCodeLink } from '../../../helpers/sourceCodeLink.js'
+
+
+
+# Frame
+
+
+
+The frame utility provides a simple way to constrain content to a consistent aspect ratio. It centers its content
+and clips any overflow, so whatever it wraps fills a fixed shape regardless of its intrinsic dimensions.
+
+While it's a natural fit for media like images and videos, the frame isn't limited to them — its primary job is
+enforcing the aspect ratio, so it works just as well for cards, map embeds, charts, or any element that should hold
+a fixed shape.
+
+See [Utility Introduction](?path=/docs/utilities-introduction--docs#higher-order-utilities-vs-components) for more information.
+
+See [Card Grid Layout](?path=/docs/recipes-layout--docs#card-grid) for an example of how frames
+can be used to keep media at a consistent aspect ratio within a card grid.
+
+Note: This utility uses the `op` prefix to avoid potential naming conflicts with other CSS frameworks.
+This is a pattern we hope to move towards for all utilities in the future.
+
+## Playground
+
+
+
+ 
+
+