the_information_nexus/tech_docs/webdev/html_css_standards.md

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

• .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

• .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>

Sections

• .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>

Forms

• .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">

Tables

• .table:
  • Description: Used to style tables of data.
  • Example: <table class="table">...</table>

Images

• .image:
  • Description: Styles generic images.

Usage of Inline and Block Elements

Understanding the difference between inline and block elements is pivotal for structuring and styling web content effectively.

Inline 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:

      <ul>
          <li>Apple</li>
          <li>Banana</li>
      </ul>
      

  • Ordered (<ol>): Numbered list.
    • Usage:

      <ol>
          <li>First item</li>
          <li>Second item</li>
      </ol>
      

  • Description (<dl>): List of terms with their descriptions.
    • Usage:

      <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:

    <blockquote cite="sourceURL">
        This is a block quote from another source.
    </blockquote>
    

• Tables (<table>): Represents tabular data.
  • Usage:

    <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.
  • Usage:

    <form action="/submit">
        <input type="text" name="name">
        <input type="submit" value="Submit">
    </form>
    

• Preformatted Text (<pre>): Displays text with whitespace preserved, often used with <code>.
  • Usage:

    <pre>
        function hello() {
            console.log("Hello, world!");
        }
    </pre>
    

• Figures (<figure> and <figcaption>): Used to mark up a photo or graphic with an optional caption.
  • Usage:

    <figure>
        <img src="path/to/image.jpg" alt="Description">
        <figcaption>Caption for the image.</figcaption>
    </figure>
    

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.