medusa/the_information_nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update tech_docs/webdev/html_css_standards.md

Browse Source
This commit is contained in:
medusa
2025-06-30 08:25:08 +00:00
parent b65a81faa4
commit 4eacddaa41
1 changed files with 263 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
tech_docs/webdev/html_css_standards.md
View File

@@ -1,194 +1,296 @@
# Coding Standards Documentation
## Introduction
This document outlines the common HTML class naming conventions and structure to ensure consistent, readable, and maintainable code in our web projects.
## Buttons
This document outlines our **HTML class naming conventions** and **structural guidelines**. Adhering to these standards ensures **consistent, readable, and maintainable code** across all web projects. Our goal is to facilitate **seamless team collaboration**, **reduce development time**, and **improve long-term code maintainability**.
- `.btn`:
- **Description**: Used to style generic buttons.
- **Example**: `<button class="btn">Click Me</button>`
- `.btn--large`:
- **Description**: Styles large buttons.
- **Example**: `<button class="btn btn--large">Large Button</button>`
- `.btn--small`:
- **Description**: Styles small buttons.
- **Example**: `<button class="btn btn--small">Small Button</button>`
-----
## Layout
## HTML Class Naming Conventions
- `.container`:
- **Description**: Wraps the main content of a web page, centering the content and limiting its width.
- **Example**: `<div class="container">...</div>`
- `.row`:
- **Description**: Creates horizontal rows of elements.
- **Example**: `<div class="row">...</div>`
- `.col`:
- **Description**: Divides a `.row` into vertical columns. Width is often defined by additional classes or styles.
- **Example**: `<div class="col">...</div>`
We'll primarily use a **BEM (Block Element Modifier)-like approach** for class naming. This method provides clarity, prevents naming collisions, and makes our CSS more modular and scalable.
## Sections
### Buttons
- `.header`:
- **Description**: Styles the top section of a web page, including the navigation bar and logo.
- **Example**: `<header class="header">...</header>`
- `.main`:
- **Description**: Styles the main content area of a web page.
- **Example**: `<main class="main">...</main>`
- `.footer`:
- **Description**: Styles the footer of a web page.
- **Example**: `<footer class="footer">...</footer>`
Buttons are fundamental interactive elements. These classes ensure consistent styling and clear intent.
## Forms
* **`.btn`**
* **Description**: Applies **base styles** to all buttons (e.g., `display`, `padding`, `border-radius`). This is the foundation for all button variations.
* **Usage**: `<button class="btn">Click Me</button>`
* **`.btn--primary`**, **`.btn--secondary`**, etc.
* **Description**: Defines different **semantic styles** for buttons (e.g., primary action, secondary action). These classes typically apply specific colors, background colors, and hover states.
* **Usage**:
* `<button class="btn btn--primary">Submit</button>`
* `<button class="btn btn--secondary">Cancel</button>`
* **`.btn--large`**, **`.btn--small`**
* **Description**: **Modifies the size** of the button, adjusting properties like `padding` and `font-size`.
* **Usage**:
* `<button class="btn btn--primary btn--large">Large Primary</button>`
* `<button class="btn btn--small">Small Button</button>`
* **`.btn--disabled`**
* **Description**: Visually indicates a **non-interactive button**, typically by dimming it and disabling pointer events.
* **Usage**: `<button class="btn btn--primary btn--disabled" disabled>Disabled Button</button>`
- `.form`:
- **Description**: Styles the entirety of forms.
- **Example**: `<form class="form">...</form>`
- `.input`:
- **Description**: Can style multiple form elements. Specific classes should be used for distinct input types.
- **Example**: `<input type="text" class="input">`
- `.text`, `.password`, `.checkbox`, `.radio`:
- **Description**: Styles individual types of inputs.
- **Examples**:
- Text: `<input type="text" class="text">`
- Password: `<input type="password" class="password">`
- Checkbox: `<input type="checkbox" class="checkbox">`
- Radio: `<input type="radio" class="radio">`
### Layout
## Tables
Layout classes help create consistent page structures and enable responsive design.
- `.table`:
- **Description**: Used to style tables of data.
- **Example**: `<table class="table">...</table>`
* **`.container`**
* **Description**: Wraps main page content, typically used to **center content** and **limit its maximum width**, often providing consistent horizontal padding.
* **Usage**: `<div class="container">...</div>`
* **`.row`**
* **Description**: Creates **horizontal groupings of elements**, often leveraging Flexbox or Grid for column arrangement.
* **Usage**: `<div class="row">...</div>`
* **`.col`**, **`.col--[breakpoint]-[size]`** (e.g., `.col--md-6`)
* **Description**: Divides a `.row` into **vertical columns**. Widths are typically defined by additional classes for responsiveness (e.g., `.col--md-6` for 50% width on medium screens and up), implying a foundational CSS grid system.
* **Usage**:
* `<div class="col">...</div>`
* `<div class="col col--md-6">...</div>`
## Images
### Sections
- `.image`:
- **Description**: Styles generic images.
These classes define the main structural blocks of a web page, improving semantic understanding and styling.
# Usage of Inline and Block Elements
* **`.header`**
* **Description**: Styles the **top section of a web page**, commonly containing the site logo, navigation, and search bar.
* **Usage**: `<header class="header">...</header>`
* **`.main`**
* **Description**: Styles the **primary content area** of a web page. Ideally, there should be only one `<main>` element per document.
* **Usage**: `<main class="main">...</main>`
* **`.footer`**
* **Description**: Styles the **bottom section of a web page**, often including copyright information or sitemaps.
* **Usage**: `<footer class="footer">...</footer class="footer">`
* **`.section`**
* **Description**: A generic class for **thematic groupings of content**, useful for applying consistent padding, margins, or background styles.
* **Usage**: `<section class="section">...</section>`
Understanding the difference between inline and block elements is pivotal for structuring and styling web content effectively.
### Forms
## Inline Elements
Form classes ensure a consistent look and feel for user input elements.
Inline elements do not start on a new line and take up as much width as necessary. They're like words in a sentence — they flow with the content.
Examples include:
- **Links (`<a>`):** Hyperlinks to another resource.
- **Usage**: `<a href="https://example.com">Visit Example</a>`
- **Images (`<img>`):** Embeds an image.
- **Usage**: `<img src="path/to/image.jpg" alt="Description">`
- **Strong Emphasis (`<strong>`):** Denotes strong importance, typically displayed as bold.
- **Usage**: `<strong>Important text.</strong>`
- **Emphasis (`<em>`):** Gives emphasized text, usually rendered as italic.
- **Usage**: `<em>Emphasized text.</em>`
- **Code (`<code>`):** Designates a single line of code.
- **Usage**: `<code>let x = 10;</code>`
- **Span (`<span>`):** Generic inline container for phrasing content. Doesn't convey any meaning on its own.
- **Usage**: `<span class="highlight">Highlighted text</span>`
- **Abbreviations (`<abbr>`):** Represents an abbreviation or acronym.
- **Usage**: `<abbr title="HyperText Markup Language">HTML</abbr>`
- **Inline Quotation (`<q>`):** Denotes a short inline quotation.
- **Usage**: `<q>Cogito, ergo sum</q>`
## Block Elements
Block elements start on a new line and typically take up the full width of their parent container.
Examples include:
- **Paragraphs (`<p>`):** Denotes a block of text.
- **Usage**: `<p>This is a paragraph.</p>`
- **Headings (`<h1>` to `<h6>`):** Mark section headings, with `<h1>` being the most prominent and `<h6>` the least.
- **Usage**:
- `<h1>Main Title</h1>`
- `<h2>Subheading</h2>`
- ...
- `<h6>Smallest Subheading</h6>`
- **Lists:**
- **Unordered (`<ul>`):** List without a specific order.
- **Usage**:
```html
<ul>
<li>Apple</li>
<li>Banana</li>
</ul>
```
- **Ordered (`<ol>`):** Numbered list.
- **Usage**:
```html
<ol>
<li>First item</li>
<li>Second item</li>
</ol>
```
- **Description (`<dl>`):** List of terms with their descriptions.
- **Usage**:
```html
<dl>
<dt>Browser</dt>
<dd>A software used to access the web.</dd>
</dl>
```
- **Divisions (`<div>`):** Generic container that groups content.
- **Usage**: `<div class="section">...</div>`
- **Block Quotation (`<blockquote>`):** Represents a section quoted from another source.
- **Usage**:
* **`.form`**
* **Description**: Styles the **entire form container**, applying general layout and spacing rules to its elements.
* **Usage**: `<form class="form">...</form>`
* **`.form__group`**
* **Description**: Groups related form elements (e.g., a label and its input) for consistent vertical spacing.
* **Usage**:
```html
<blockquote cite="sourceURL">
This is a block quote from another source.
</blockquote>
<div class="form__group">
<label for="username">Username:</label>
<input type="text" id="username" class="input">
</div>
```
- **Tables (`<table>`):** Represents tabular data.
- **Usage**:
* **`.input`**
* **Description**: Applies **base styles to generic text-based input fields** (`<input type="text">`, `<input type="password">`, `<textarea>`, `<select>`).
* **Usage**: `<input type="text" class="input">`
* **`.input--[type]`** (e.g., `.input--checkbox`, `.input--radio`)
* **Description**: **Specific modifier classes for distinct input types** that require unique styling beyond the base `.input` class.
* **Usage**:
* `<input type="checkbox" class="input--checkbox">`
* `<input type="radio" class="input--radio">`
* **`.input--error`**, **`.input--success`**
* **Description**: Visual feedback classes for **validation states**.
* **Usage**:
* `<input type="text" class="input input--error">`
* `<input type="text" class="input input--success">`
### Tables
Table classes provide structured data presentation.
* **`.table`**
* **Description**: Applies base styles to **tabular data**, such as borders, padding, and font styles for `<table>`, `<th>`, and `<td>` elements.
* **Usage**:
```html
<table>
<tr>
<th>Header 1</th>
<th>Header 2</th>
</tr>
<tr>
<td>Data 1</td>
<td>Data 2</td>
</tr>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Age</th>
</tr>
</thead>
<tbody>
<tr>
<td>Alice</td>
<td>30</td>
</tr>
</tbody>
</table>
```
- **Forms (`<form>`):** Represents an interactive form.
- **Usage**:
* **`.table--striped`**
* **Description**: Adds **alternating background colors** to table rows for improved readability.
* **Usage**: `<table class="table table--striped">...</table>`
* **`.table--responsive`**
* **Description**: Ensures the table is **horizontally scrollable** on smaller screens, preventing layout breaks.
* **Usage**: `<div class="table--responsive"><table class="table">...</table></div>`
### Images
Classes for images ensure proper display and responsiveness.
* **`.image`**
* **Description**: Applies **generic styling to images**, such as `display: block` or default `max-width`.
* **Usage**: `<img src="path/to/image.jpg" class="image" alt="Description">`
* **`.image--responsive`**
* **Description**: Ensures images **scale fluidly with their parent container** by setting `max-width: 100%` and `height: auto`.
* **Usage**: `<img src="path/to/image.jpg" class="image image--responsive" alt="Description">`
* **`.image--circle`**
* **Description**: Styles an image into a **perfect circle**, useful for avatars or profile pictures.
* **Usage**: `<img src="path/to/avatar.jpg" class="image--circle" alt="User Avatar">`
-----
## Usage of Inline and Block Elements
Understanding the intrinsic display behavior of HTML elements is crucial for effective content structuring and styling. Correct element choice enhances semantic value, improves accessibility, and simplifies CSS.
### Inline Elements
**Inline elements** do not start on a new line and take up only as much width as their content requires. They flow within the text, like words in a sentence. You generally **cannot set `width` or `height`** directly on inline elements, and vertical margins (`margin-top`, `margin-bottom`) have no effect.
**Common Inline Elements & Usage**:
* **Links (`<a>`)**: Hyperlinks to other resources.
* **Usage**: `<a href="https://example.com">Visit Example</a>`
* **Images (`<img>`)**: Embeds an image. While `<img>` allows `width`/`height`, it behaves as inline in terms of text flow.
* **Usage**: `<img src="path/to/image.jpg" alt="Description of image">`
* **Strong Emphasis (`<strong>`)**: Denotes strong importance; typically displayed as bold.
* **Usage**: `<strong>Important text.</strong>`
* **Emphasis (`<em>`)**: Gives emphasized text; usually rendered as italic.
* **Usage**: `<em>Emphasized text.</em>`
* **Code (`<code>`)**: Designates a short fragment of computer code.
* **Usage**: `<code>let x = 10;</code>`
* **Span (`<span>`)**: A generic inline container with no semantic meaning. Primarily used for applying styles or JavaScript to a specific piece of text.
* **Usage**: `<span class="highlight">Highlighted text</span>`
* **Abbreviations (`<abbr>`)**: Represents an abbreviation or acronym.
* **Usage**: `<abbr title="HyperText Markup Language">HTML</abbr>`
* **Inline Quotation (`<q>`)**: Denotes a short inline quotation.
* **Usage**: `<q>Cogito, ergo sum</q>`
### Block Elements
**Block elements** always start on a new line and typically take up the full available width of their parent container. You **can set `width`, `height`, and all margin/padding properties** on block elements.
**Common Block Elements & Usage**:
* **Paragraphs (`<p>`)**: Denotes a block of text.
* **Usage**: `<p>This is a paragraph.</p>`
* **Headings (`<h1>` to `<h6>`)**: Mark section headings. Essential for document structure and SEO.
* **Usage**: `<h1>Main Title</h1>`, `<h2>Subheading</h2>`, etc.
* **Lists**:
* **Unordered (`<ul>`)**: List of items without a specific order.
```html
<form action="/submit">
<input type="text" name="name">
<input type="submit" value="Submit">
</form>
<ul>
<li>Apple</li>
<li>Banana</li>
</ul>
```
- **Preformatted Text (`<pre>`):** Displays text with whitespace preserved, often used with `<code>`.
- **Usage**:
* **Ordered (`<ol>`)**: Numbered list where item order is significant.
```html
<pre>
function hello() {
console.log("Hello, world!");
}
</pre>
<ol>
<li>First item</li>
<li>Second item</li>
</ol>
```
- **Figures (`<figure>` and `<figcaption>`):** Used to mark up a photo or graphic with an optional caption.
- **Usage**:
* **Description (`<dl>`)**: List of terms with their corresponding descriptions.
```html
<figure>
<img src="path/to/image.jpg" alt="Description">
<figcaption>Caption for the image.</figcaption>
</figure>
<dl>
<dt>Browser</dt>
<dd>A software used to access the web.</dd>
</dl>
```
* **Divisions (`<div>`)**: A generic block-level container. It has no semantic meaning and is primarily used for layout or styling when no other semantic element is appropriate.
* **Usage**: `<div class="section-wrapper">...</div>`
* **Block Quotation (`<blockquote>`)**: Represents a section quoted from another source, typically displayed with indentation.
```html
<blockquote cite="sourceURL">
This is a block quote from another source.
</blockquote>
```
* **Tables (`<table>`)**: Represents tabular data.
```html
<table>
<tr>
<th>Header 1</th>
<th>Header 2</th>
</tr>
<tr>
<td>Data 1</td>
<td>Data 2</td>
</tr>
</table>
```
* **Forms (`<form>`)**: Represents an interactive form for submitting user input.
```html
<form action="/submit-data" method="POST">
<label for="email">Email:</label>
<input type="email" id="email" name="email">
<button type="submit">Send</button>
</form>
```
* **Preformatted Text (`<pre>`)**: Displays text with whitespace and line breaks preserved, often used with `<code>` for multi-line code.
```html
<pre>
function greet(name) {
console.log("Hello, " + name + "!");
}
</pre>
```
* **Figures (`<figure>` and `<figcaption>`)**: Marks up self-contained content (like a photo or chart) with an optional caption.
```html
<figure>
<img src="path/to/chart.png" alt="Sales Chart">
<figcaption>Quarterly sales performance.</figcaption>
</figure>
```
### When to Change Display Properties
While elements have default display types, CSS allows you to change them using the `display` property.
* **`display: inline-block;`**: A hybrid display type. Elements behave like inline elements (they don't force a new line) but allow you to set `width`, `height`, and vertical `margin`/`padding`. Ideal for navigation items or icons with specific spacing.
* **`display: flex;` / `display: grid;`**: These are powerful layout systems. When a container uses `display: flex;` or `display: grid;`, its children become flex or grid items, enabling complex alignment and distribution.
-----
## General Best Practices & Principles
Beyond specific classes, these principles guide our overall coding approach for quality and maintainability.
### 1\. Semantic HTML
* **Description**: Use HTML tags that convey the **meaning and structure of the content**, not just how it looks. For example, use `<button>` for buttons, `<nav>` for navigation, and `<section>` for distinct content blocks, rather than just `<div>` everywhere.
* **Benefit**: Improves accessibility, SEO, and makes the code easier to understand for other developers.
### 2\. Class Naming Philosophy (BEM-like)
* **Description**: Our BEM-like methodology defines relationships:
* **Block**: Standalone entity (e.g., `.header`, `.btn`).
* **Element**: Part of a block, specific to that block (e.g., `.form__group`, `.table__cell`). Use two underscores `__`.
* **Modifier**: Flag on a block or element to change its appearance or behavior (e.g., `.btn--large`, `.input--error`). Use two hyphens `--`.
* **Benefit**: Provides clear relationships, prevents naming collisions, and makes CSS more modular and scalable.
### 3\. Avoid Over-nesting
* **Description**: Keep your HTML structure as **flat as possible** while maintaining semantic meaning. Deeply nested `<div>`s can lead to overly specific CSS selectors and difficult refactoring.
* **Benefit**: Improves CSS performance, readability, and maintainability.
### 4\. Accessibility (A11y) Considerations
* **Description**: Always consider how your code will be perceived by users with disabilities.
* Use **meaningful `alt` attributes** for all `<img>` tags.
* Provide **labels for form inputs** (`<label for="id">`).
* Ensure **sufficient color contrast**.
* Consider **keyboard navigation** and `tabindex`.
* **Benefit**: Makes our applications usable by a wider audience and complies with accessibility standards.
### 5\. Comments (When Necessary)
* **Description**: Add HTML comments (\`\`) to **explain complex or non-obvious sections** of code, or to mark significant sections. Avoid commenting on obvious code.
* **Benefit**: Helps future developers (and your future self) understand the intent behind specific code blocks.
-----
## Conclusion
Choosing the correct element—whether inline or block—enhances the semantic value of the content, improves accessibility, and makes styling more straightforward.
- **Example**: `<img src="path/to/image.jpg" class="image" alt="Description">`
- `.img-responsive`:
- **Description**: Ensures images are responsive and adjust to their container's width.
- **Example**: `<img src="path/to/image.jpg" class="img-responsive" alt="Description">`
## Conclusion
By adhering to these naming conventions and standards, we ensure that our code remains consistent across projects, making it easier for developers to collaborate, maintain, and extend the codebase.
By adhering to these **naming conventions, structural guidelines, and best practices**, our codebase will remain **consistent, readable, and highly maintainable** across all projects. This collaborative approach fosters easier teamwork, reduces debugging time, and ultimately leads to more robust and scalable web applications.