Skip to content

Document device-independent units and their relationship to platform-specific units #3036

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
Merged
merged 5 commits into from
Nov 12, 2025
Merged

Document device-independent units and their relationship to platform-specific units #3036

merged 5 commits into from
Nov 12, 2025

Conversation

Copy link
Contributor

Copilot AI commented Sep 19, 2025 •
edited by github-actions bot
Loading

  • Analyze existing mentions of device-independent units in the documentation
  • Create a new comprehensive documentation file for device-independent units
  • Explain the concept and relationship to platform-specific units (iOS points, Android dp, etc.)
  • Add cross-references from existing files that mention device-independent units
  • Update the Table of Contents to include the new documentation
  • Test markdown linting and validation
  • Review and refine the documentation based on .NET MAUI source verification
  • Address markdownlint errors (MD032 and MD047)

Summary

Successfully implemented comprehensive documentation for device-independent units in .NET MAUI and addressed all review feedback.

Latest Changes (this commit)

Fixed markdownlint errors in device-independent-units.md:

  • Added blank lines before all lists (MD032) at lines 28, 36, 44, 51, and 124
  • Added single trailing newline at end of file (MD047)

Documentation Created

  • /docs/user-interface/device-independent-units.md (217 lines) - Complete reference explaining:
    • What device-independent units are and their purpose (1/160th inch physical size)
    • 1:1 mapping to platform-specific units:
      • iOS: 1 DIU = 1 point
      • Android: 1 DIU = 1 dp (density-independent pixel)
      • Windows: 1 DIU = 1 device-independent pixel
      • macOS: 1 DIU = 1 point
    • Practical examples for layouts, fonts, animations, and responsive design
    • Best practices for touch targets and common spacing values
    • Related concepts and cross-references

Cross-References Added

Updated 6 existing files to link to the new documentation:

  • fonts.md - FontSize and font icon Size properties
  • align-position.md - Margin/padding measurements
  • fundamentals/gestures/swipe.md - SwipeGestureRecognizer.Threshold
  • fundamentals/triggers.md - AdaptiveTrigger window measurements
  • user-interface/includes/basic-animation-dotnet10.md - TranslateToAsync parameters
  • TOC.yml - Added under User Interface > Controls section

Fixes #1042.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Internal previews

📄 File 🔗 Preview link
docs/fundamentals/gestures/swipe.md docs/fundamentals/gestures/swipe
docs/fundamentals/triggers.md docs/fundamentals/triggers
docs/user-interface/align-position.md docs/user-interface/align-position
docs/user-interface/device-independent-units.md docs/user-interface/device-independent-units
docs/user-interface/fonts.md docs/user-interface/fonts

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Sep 19, 2025

Learn Build status updates of commit 507100a:

✅ Validation status: passed

For more details, please refer to the build report.

@jfversluis
Add comprehensive device-independent units documentation
ea28a1a 
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Sep 19, 2025

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Sep 19, 2025

Learn Build status updates of commit ea28a1a:

✅ Validation status: passed

File Status Preview URL Details
docs/fundamentals/gestures/swipe.md ✅Succeeded View (>=net-maui-8.0)
docs/fundamentals/triggers.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/align-position.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/device-independent-units.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/fonts.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/includes/basic-animation-dotnet10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

Copilot AI changed the title [WIP] Document the definition of Device-Independent Units on MAUI Document device-independent units and their relationship to platform-specific units Sep 19, 2025
Copilot AI requested a review from jfversluis September 19, 2025 19:44
Copilot finished work on behalf of jfversluis September 19, 2025 19:44
jfversluis
jfversluis reviewed Nov 11, 2025
View reviewed changes
@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@jfversluis jfversluis marked this pull request as ready for review November 11, 2025 12:24
@jfversluis jfversluis requested a review from a team as a code owner November 11, 2025 12:24
@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

Learn Build status updates of commit 44cef38:

✅ Validation status: passed

File Status Preview URL Details
docs/fundamentals/gestures/swipe.md ✅Succeeded View (>=net-maui-8.0)
docs/fundamentals/triggers.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/align-position.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/device-independent-units.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/fonts.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/includes/basic-animation-dotnet10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

Learn Build status updates of commit 053857c:

✅ Validation status: passed

File Status Preview URL Details
docs/fundamentals/gestures/swipe.md ✅Succeeded View (>=net-maui-8.0)
docs/fundamentals/triggers.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/align-position.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/device-independent-units.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/fonts.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/includes/basic-animation-dotnet10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@jfversluis
Copy link
Member

jfversluis commented Nov 11, 2025

@copilot please address these

Error: docs/user-interface/device-independent-units.md:28 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- 1 device-independent unit = ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
Error: docs/user-interface/device-independent-units.md:36 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- 1 device-independent unit = ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
Error: docs/user-interface/device-independent-units.md:44 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- 1 device-independent unit = ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
Error: docs/user-interface/device-independent-units.md:51 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- 1 device-independent unit = ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
Error: docs/user-interface/device-independent-units.md:124 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- iOS: 16 points"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
Error: docs/user-interface/device-independent-units.md:211:76 MD047/single-trailing-newline Files should end with a single newline character https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md047.md
Error: Failed with exit code: 1

@jfversluis
Fix markdownlint errors: add blank lines before lists and trailing ne…
0704318 
…wline

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Nov 11, 2025

@copilot please address these

Error: docs/user-interface/device-independent-units.md:28 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- 1 device-independent unit = ...

Fixed all markdownlint errors in commit 0704318:

  • Added blank lines before lists (MD032) at lines 28, 36, 44, 51, and 124
  • Added single trailing newline at end of file (MD047)

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

Learn Build status updates of commit 0704318:

✅ Validation status: passed

File Status Preview URL Details
docs/fundamentals/gestures/swipe.md ✅Succeeded View (>=net-maui-8.0)
docs/fundamentals/triggers.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/align-position.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/device-independent-units.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/fonts.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/includes/basic-animation-dotnet10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

learn-build-service-prod bot commented Nov 11, 2025

Learn Build status updates of commit 0704318:

✅ Validation status: passed

File Status Preview URL Details
docs/fundamentals/gestures/swipe.md ✅Succeeded View (>=net-maui-8.0)
docs/fundamentals/triggers.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/align-position.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/device-independent-units.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/fonts.md ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/includes/basic-animation-dotnet10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

Copilot AI requested a review from jfversluis November 11, 2025 13:33
Copilot finished work on behalf of jfversluis November 11, 2025 13:33
@jfversluis jfversluis merged commit 276ada3 into main Nov 12, 2025
9 checks passed
@jfversluis jfversluis deleted the copilot/fix-1042 branch November 12, 2025 09:05
jfversluis added a commit that referenced this pull request Nov 12, 2025
@dotnet-policy-service @jfversluis
Merge main into live (#3083)
284a46c 
* Add documentation for Windows ARM device limitations with Android emulators (#3038)

* Initial plan

* Add Windows ARM device limitations documentation for Android emulators

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com>

* Document WebView2/BlazorWebView/HybridWebView issues with Program Files installation (#3035)

* Initial plan

* Add Windows Program Files warning for WebView2/BlazorWebView/HybridWebView

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

* Extract WebView2 Program Files warning into reusable include snippet

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

* Fix markdown linting errors in webview2-program-files-warning.md

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com>

* Document device-independent units and their relationship to platform-specific units (#3036)

* Initial plan

* Add comprehensive device-independent units documentation

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

* Update docs/user-interface/device-independent-units.md

* Fix markdownlint errors: add blank lines before lists and trailing newline

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com>

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@PureWeen PureWeen PureWeen approved these changes

@jfversluis jfversluis Awaiting requested review from jfversluis

Assignees

@jfversluis jfversluis

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document the definition of Device-Independent Units on MAUI

3 participants

@jfversluis @PureWeen