Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add docs for utilities #196

Open
wants to merge 6 commits into
base: 5.x
Choose a base branch
from
Open

Add docs for utilities #196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a65fb2f
add docs for utilities
andersonjeccel Jun 26, 2024
970814b
fix vale
favour-chibueze Jul 26, 2024
8547dbc
fix vale error
favour-chibueze Jul 30, 2024
762fabb
fix vale
favour-chibueze Jul 30, 2024
1a934b2
fix vale
favour-chibueze Jul 30, 2024
454eb5b
Merge branch '5.x' into docs-utilities
favour-chibueze Jul 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 229 additions & 0 deletions docs/design/utilities.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,229 @@
Utilities
=========

Introduction
------------

Mautic offers a set of CSS utility classes designed to facilitate efficient implementation of flexible layouts using CSS flex-box. These utilities provide a systematic approach to constructing responsive and dynamic new areas for its User interface, enabling you to rapidly prototype and build complex layouts while minimizing custom CSS.

The utility classes seek to encompass a great spectrum of flex-box properties, including:

- Display settings
- Flex direction
- Wrapping behavior
- Justification and alignment
- Spacing and gap management
- Item ordering

Key aspects
^^^^^^^^^^^^

1. **Abbreviated Nomenclature**: class names follow a logical, short and easy-to-remember convention.
2. **Most Common Uses Coverage**: utilities address the full range of flex-box properties and behaviors.
3. **Responsive Design**: includes variations for different view port sizes, enabling fine-grained control over layout across devices.
.. vale off

4. **Composability**: you can combine classes to create sophisticated layout patterns.

Check failure on line 26 in docs/design/utilities.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Composability'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Composability'?", "location": {"path": "docs/design/utilities.rst", "range": {"start": {"line": 26, "column": 6}}}, "severity": "ERROR"}

.. vale on

5. **Consistent Spacing**: standardized options for managing padding, margin and gap properties.

This documentation clearly explains each utility class, its function, and its app. It includes practical examples and best practices for combining utilities to achieve complex layout requirements.

The following sections detail the individual utility classes, their usage, and advanced implementation strategies. This resource helps front-end developers efficiently leverage flex-box in their projects.


Abbreviation keys
----------------

.. vale off

- **d**: display
- **fd**: flex-direction
- **fw**: flex-wrap
- **jc**: justify-content
- **ai**: align-items
- **ac**: align-content
- **as**: align-self
- **fg**: flex-grow
- **fs**: flex-shrink
- **fb**: flex-basis
- **fo**: order

.. vale on

Flex container properties
-------------------------

.. vale off

- ``.d-flex``: Sets an element to be a flex container by setting its display property to flex. It allows the direct children of the element to be laid out in a flex context.
- ``.fd-row``: Sets the direction of the flex items in the container to a row. The items are laid out from left to right.
- ``.fd-row-reverse``: Sets the direction of the flex items in the container to a row, but in reverse. The items are laid out from right to left.
- ``.fd-column``: Sets the direction of the flex items in the container to a column. The items are laid out from top to bottom.
- ``.fd-column-reverse``: Sets the direction of the flex items in the container to a column, but in reverse. The items are laid out from bottom to top.
- ``.fw-wrap``: Allows the flex items to wrap onto multiple lines if there isn't enough room for them on one line.
- ``.fw-nowrap``: Prevents the flex items from wrapping onto multiple lines, even if there isn't enough room for them on one line.
- ``.fw-wrap-reverse``: Allows the flex items to wrap onto multiple lines if there isn't enough room for them on one line, but in reverse.
- ``.jc-start``: Aligns the flex items along the start of the main axis. In a row direction, this is the left edge, and in a column direction, this is the top edge.
- ``.jc-end``: Aligns the flex items along the end of the main axis. In a row direction, this is the right edge, and in a column direction, this is the bottom edge.
- ``.jc-center``: Aligns the flex items along the center of the main axis.
- ``.jc-space-between``: Evenly distributes the flex items along the main axis, with the first item at the start and the last item at the end.
- ``.jc-space-around``: Evenly distributes the flex items along the main axis, with equal space around each item.
- ``.jc-space-evenly``: Evenly distributes the flex items along the main axis, with equal space between each item, including the first and last items.
- ``.ai-start``: Aligns the flex items along the start of the cross axis. In a row direction, this is the top edge, and in a column direction, this is the left edge.
- ``.ai-end``: Aligns the flex items along the end of the cross axis. In a row direction, this is the bottom edge, and in a column direction, this is the right edge.
- ``.ai-center``: Aligns the flex items along the center of the cross axis.
- ``.ai-baseline``: Aligns the flex items along their baseline. The baseline is the line upon which the letters in a line of text would rest.
- ``.ai-stretch``: Stretches the flex items to fill the container along the cross axis.
- ``.ac-start``: Aligns the lines of flex items along the start of the cross axis when there is extra space in the cross axis.
- ``.ac-end``: Aligns the lines of flex items along the end of the cross axis when there is extra space in the cross axis.
- ``.ac-center``: Aligns the lines of flex items along the center of the cross axis when there is extra space in the cross axis.
- ``.ac-space-between``: Evenly distributes the lines of flex items along the cross axis, with the first line at the start and the last line at the end, when there is extra space in the cross axis.
- ``.ac-space-around``: Evenly distributes the lines of flex items along the cross axis, with equal space around each line, when there is extra space in the cross axis.
- ``.ac-stretch``: Stretches the lines of flex items to fill the container along the cross axis when there is extra space in the cross axis.
- ``.as-start``: Aligns a single flex item along the start of the cross axis.
- ``.as-end``: Aligns a single flex item along the end of the cross axis.
- ``.as-center``: Aligns a single flex item along the center of the cross axis.
- ``.as-baseline``: Aligns a single flex item along the baseline.
- ``.as-stretch``: Stretches a single flex item to fill the container along the cross axis.
- ``.fg-1``: Sets the flex grow factor of a flex item to 1. This means the item will grow to fill any remaining space in the container.
- ``.fg-0``: Sets the flex grow factor of a flex item to 0. This means the item will not grow to fill any remaining space in the container.
- ``.fs-1``: Sets the flex shrink factor of a flex item to 1. This means the item can shrink if necessary to fit into the container.
- ``.fs-0``: Sets the flex shrink factor of a flex item to 0. This means the item cannot shrink to fit into the container.
- ``.fb-auto``: Sets the flex basis of a flex item to auto. This means the browser will calculate the size of the item based on its content.
- ``.fb-0``: Sets the flex basis of a flex item to 0. This means the item will have a size of 0 before any growing or shrinking takes place.
- ``.fo-auto``: Sets the order of a flex item to auto. This means the item will be laid out in the order it appears in the source code.
- ``.fo-0``, ``.fo-1``, ``.fo-2``, ``.fo-3``, ``.fo-4``, ``.fo-5``: Sets the order of a flex item to the specified number. This means the item will be laid out in that order, regardless of where it appears in the source code.
- ``.gap-20``, ``.gap-lg``: Sets the gap between flex items to 20px.
- ``.gap-15``, ``.gap-md``: Sets the gap between flex items to 15px.
- ``.gap-10``, ``.gap-sm``: Sets the gap between flex items to 10px.
- ``.gap-5``, ``.gap-xs``: Sets the gap between flex items to 5px.
- ``.gap-4``: Sets the gap between flex items to 4px.
- ``.gap-3``: Sets the gap between flex items to 3px.
- ``.gap-2``: Sets the gap between flex items to 2px.
- ``.gap-1``: Sets the gap between flex items to 1px.
- ``.gap-0``: Sets the gap between flex items to 0px.

.. vale on

Responsive variations
---------------------

The utilities follow a mobile-first responsive design principle, becoming active at specific minimum screen sizes. You create these responsive variations by appending ``-sm``, ``-md``, or ``-lg`` to the end of the utility class name.

- Base utility no suffix: applies to all screen sizes
- ``-sm`` suffix: Applies from the small breakpoint and up
- ``-md`` suffix: Applies from the medium breakpoint and up
- ``-lg`` suffix: Applies from the large breakpoint and up

For example:

- ``.d-flex`` applies to all screen sizes
- ``.d-flex-sm`` applies from the small breakpoint and up
- ``.d-flex-md`` applies from the medium breakpoint and up
- ``.d-flex-lg`` applies from the large breakpoint and up

This approach allows for progressive enhancement of layouts as the view-port size increases, providing fine-grained control over the responsiveness of your design.


Usage examples
--------------

Here are some example scenarios that illustrate how to use these utilities in practice:

.. code-block:: html

<div class="d-flex jc-space-between ai-center">
<div>Left content</div>
<div>Center content</div>
<div>Right content</div>
</div>

This example creates a flex container with items spread across the container and vertically centered.

.. code-block:: html

<div class="d-flex fd-column ai-stretch gap-10">
<div>Top item</div>
<div>Middle item</div>
<div>Bottom item</div>
</div>

This example creates a vertical stack of items that stretch to fill the container's width, with a 10px gap between them.

Combining utilities
-------------------

Note that you can combine these utilities to create complex layouts. For example:

.. code-block:: html

<div class="d-flex fd-row-md fd-column fw-wrap jc-center ai-center gap-15">
<!-- Flex items here -->
</div>

This combination creates a flex container that:

- Is a column on small screens and a row on medium screens and up
- Wraps items if they don't fit
- Centers items both horizontally and vertically
- Has a 15px gap between items

Padding and margin utilities
============================

The CSS utility classes for padding and margin provide a comprehensive set of options for controlling spacing within your layouts. These utilities follow a consistent naming convention and offer a range of predefined sizes, including pixel values and variable-based spacing.

Naming convention
-----------------

The utility classes use the following prefixes:

- ``pa-``: padding all sides
- ``pt-``: padding top
- ``pr-``: padding right
- ``pb-``: padding bottom
- ``pl-``: padding left
- ``ma-``: margin all sides
- ``mt-``: margin top
- ``mr-``: margin right
- ``mb-``: margin bottom
- ``ml-``: margin left

Size options
------------

The utilities offer the following size options:

.. vale off

1. Pixel-based sizes: 0, 1, 2, 3, 4, 5, 10, 15, 20 pixels
2. Variable-based sizes: 8, 12, 16, 24, 32, 40, 48, 64, 80, 96, 160 pixels (using CSS variables)
3. Named sizes: xs (5px), sm (10px), md (15px), lg (20px), xl (32px)

.. vale on

Usage examples
--------------

.. code-block:: html

<div class="pa-5">Padding 5px on all sides</div>
<div class="pt-10 pb-10">Padding 10px on top and bottom</div>
<div class="pl-md pr-md">Padding 15px on left and right</div>
<div class="ma-lg">Margin 20px on all sides</div>
<div class="mt-32 mb-32">Margin 32px on top and bottom</div>

Variable-based sizes
--------------------

Some utilities use CSS variables for spacing, allowing for easy theming and consistent spacing across your app:

- ``var(--spacing-03)`` to ``var(--spacing-13)``

These correspond to specific pixel values (for example, ``var(--spacing-03)`` is 8px, ``var(--spacing-13)`` is 160px).

.. note::
All padding and margin utilities use the ``!important`` declaration to ensure they take precedence over other styles. Use these utilities judiciously to maintain the integrity of your CSS architecture.
7 changes: 7 additions & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,13 @@ There are several ways to support Mautic other than contributing with code.
development-environment/setup
development-environment/environments

.. toctree::
:maxdepth: 2
:caption: Design and UX
:hidden:

design/utilities

.. toctree::
:maxdepth: 2
:caption: Themes
Expand Down
Loading